Introduction

As you scroll through the page, you can follow these code snippets.

The VCOM API enables you to directly access your data on the meteocontrol platform. Some resources are read-only, others can be created or modified.

Access to the VCOM API requires an API-Key as well as credentials to our platform (VCOM only). As a partner of meteocontrol we will provide you an API-Key.

Intended Audience

This guide is intended to assist software developers who want to develop applications by using the VCOM API. It assumes the reader has a general understanding of web services and is familiar with the following technologies:

RESTful web services
HTTP/1.1 conventions
JSON format

Getting Started

Code snippet

    curl
    -u username:password
    -H "X-API-KEY: apiKey"
    'https://api.meteocontrol.de/v2/<endpoint>'

<?php
    use meteocontrol\client\vcomapi\ApiClient;

    require_once __DIR__ . '/vendor/autoload.php';
    $api = ApiClient::get('username', 'password', 'apiKey');

Whether you’re using curl, a client provided by meteocontrol or your own implementation, you will need to have the following information ready:

API-Key

As a partner you’ll find your individual key in the administration section of VCOM.
If you are developing for one of our partners, you can obtain this information through them.
Please contact one of our sales offices if you are a 3rd party not directly related to any of our partners.

Credentials (username, password)

Resources within the VCOM API can be accessed using the same credentials used for VCOM itself.

Resources

We provide an always up-to-date PHP client, and blueprint clients for other languages to help you get started. Please visit our GitHub Page to find out more about using meteocontrol’s API Clients in your projects.

Look to the right for examples using curl and our PHP client.

Datacenter

The meteocontrol VCOM API can be found at:

All countries: https://api.meteocontrol.de
Clients on the Chinese datacenter: https://api.meteocontrol.cn

Authentication

Request (Basic)

curl
-u username:password
-H "X-API-KEY: <apiKey>"
'https://api.meteocontrol.de/v2/<endpoint>'

Request (OAuth)

curl
-H "X-API-KEY: <apiKey>"
-H "Authorization: Bearer <Access Token>"
'https://api.meteocontrol.de/v2/<endpoint>'

The API requires you to authenticate using OAuth Authentication or Basic Authentication with an API-Key. Each request must include the following headers:

Header field name	Header field value	Description
Authorization `required`	`Bearer <Access Token>` or `Basic <base64(username:password)>`	Provide an OAuth access token from login endpoint*, or provide a base64 encoded basic authorization token.(Deprecated)
X-API-KEY `required`	`<apiKey>`	Replace `<apiKey>` with your API-Key.

*To use OAuth authorization, please read here for more information.

While using Basic authorization, given meteocontrol as the username, secret as the password and abcdef as the API-Key the headers are formed as follows:

Authorization: Basic bWV0ZW9jb250cm9sOnNlY3JldA==
X-API-KEY: abcdef

Rate Limiting

The number of requests is limited depending on the level of your API-Key.

API Level	Calls per minute	Calls per day
API 500	30	500
API 10.000	90	10.000
API 100.000	270	100.000
API 150.000	360	150.000

Every request will be answered with a rate limit information in the response headers:

Header field name	Description
X-RateLimit-Reset-Minute	The time at which the current minute rate limit resets in RFC 7231 format.
X-RateLimit-Limit-Minute	The maximum number of requests that the client is permitted to make per minute.
X-RateLimit-Remaining-Minute	The number of requests remaining in the current minute rate limit window.
X-RateLimit-Reset-Day	The time at which the current day rate limit resets in RFC 7231 format.
X-RateLimit-Limit-Day	The maximum number of requests that the client is permitted to make per day.
X-RateLimit-Remaining-Day	The number of requests remaining in the current day rate limit window.

A typical response might look like this:

HTTP/1.1 200 OK
Date: Thu, 25 Feb 2016 10:31:57 GMT
X-RateLimit-Reset-Minute: Thu, 25 Feb 2016 10:32:57 GMT
X-RateLimit-Limit-Minute: 100
X-RateLimit-Remaining-Minute: 99
X-RateLimit-Reset-Day: Thu, 25 Feb 2016 14:51:02 GMT
X-RateLimit-Limit-Day: 100000
X-RateLimit-Remaining-Day: 99999

When either minute or day rate limit is exceeded the server will respond with the 429 status code:

HTTP/1.1 429 Too Many Requests
Date: Thu, 25 Feb 2016 11:03:53 GMT
X-RateLimit-Reset-Minute: Thu, 25 Feb 2016 11:04:45 GMT
X-RateLimit-Limit-Minute: 10
X-RateLimit-Remaining-Minute: 0
X-RateLimit-Reset-Day: Fri, 26 Feb 2016 10:31:31 GMT
X-RateLimit-Limit-Day: 500
X-RateLimit-Remaining-Day: 328

Cache

Request

curl
-u username:password
-H "X-API-KEY: 1234567890"
-H "Cache-Control: no-cache"
'https://api.meteocontrol.de/v2/<endpoint>'

The API allows user specify cache mode for each request, if there’s no Cache-Control header given the API will use cache by default.

Header field name	Header field value	Description
Cache-Control `optional`	`no-cache`	Disable cache

Timestamps

All provided timestamps must comply to the ISO-8601 standard with the exception that the week dates and ordinal dates notation is not supported. The VCOM-API will always return full ISO-8601 timestamps.

When requesting data it’s allowed to omit parts of the timestamp starting from the end, meaning 2010-01-01 is still valid and may be used for endpoints which return daily data. 2010-01 for endpoints returning monthly data, and so on. If parts of the timestamp are omitted the date will be initialized with zeros (2010-01-01 => 2010-01-01 00:00:00), please take this into account when requesting interval data.

If no timezone is provided, the timezone of the related power plant will be determined and used for the returned data. The power plant timezone will also be used in cases where the from and to timezones don’t match.

Complied timestamp format examples

2010
2010-01
2010-01-01 00:00
2010-01-01 00:00:00
2010-01-01T00:00
2010-01-01T00:00:00
2010-01-01T00:00:00Z
2010-01-01T00:00:00+0000
2010-01-01T00:00:00+00:00

Content Encoding

Request

curl
--compressed 
-u username:password
-H "X-API-KEY: 1234567890"
'https://api.meteocontrol.de/v2/<endpoint>'

The API supports standard HTTP content-encoding. If there’s no Accept-Encoding header present, an unsupported algorithm was requested, or the response size is below 512 bytes, the API will not compress the response.

Note: The official client libraries always request gzip encoded content.

Header field name	Header field value	Description
Accept-Encoding `optional`	`gzip`ǀ`deflate`	Comma separated list of compression algorithms

Errors

Error Code	Meaning
400	Bad request. Possible reasons: Malformed request parameters Missing request parameters Invalid json data provided
401	Unauthorized. Possible reasons: Basic Authentication failed No API-key was provided An invalid API-Key was provided
403	Forbidden. Possible reasons: User is not authorized to access the system User is not authorized to access the ticket
404	Endpoint not found. Possible reasons: Route is not found Request an invalid device ID Request an invalid abbreviation ID Request an invalid comment ID
405	Method not allowed (See the returned `Allow` header for the set of methods supported by the resource)
429	Too Many Requests (Rate limit exceeded)
500	Unexpected Internal Error. Our IT department has been notified and will look into this issue shortly - Try again later.

Endpoints

Session

Get one session object

Request

curl 'https://api.meteocontrol.de/v2/session'

<?php
    /** @var Session $session */
    $session = $api->session()->get();

Response

{
  "data": {
    "user": {
      "id": "123",
      "title": "Mr.",
      "firstName": "First Name",
      "lastName": "Last Name",
      "username": "user.name",
      "email": "example@example.com",
      "language": "en",
      "company": "Company",
      "fax": "0234567890",
      "telephone": "0234567891",
      "cellphone": "0987654321",
      "address": {
        "city": "City",
        "country": "Country",
        "postalCode": "12345",
        "street": "Street 123",
        "streetAddition": "2F-1"
      },
      "timezone": {
        "name": "Europe/Berlin",
        "utcOffset": "+02:00"
      },
      "hasVcom": true
    }
  }
}

<?php
    /** @var Session $session */
    echo $session->user->id;// "123"
    echo $session->user->title;// 'Mr.'
    echo $session->user->firstName;// 'First Name'
    echo $session->user->lastName;// 'Last Name'
    echo $session->user->username;// 'user.name'
    echo $session->user->email;// 'example@example.com'
    echo $session->user->language;// 'en'
    echo $session->user->company;// 'Company'
    echo $session->user->fax;// '0234567890'
    echo $session->user->telephone;// '0234567891'
    echo $session->user->cellphone;// '0987654321'
    echo $session->user->address->city;// 'City'
    echo $session->user->address->country;// 'Country'
    echo $session->user->address->postalCode;// '12345'
    echo $session->user->address->street;// 'Street 123'
    echo $session->user->address->streetAddition;// '2F-1'
    echo $session->user->timezone->name;// 'Europe/Berlin'
    echo $session->user->timezone->utcOffset;// '+02:00'
    echo $session->user->hasVcom;// true

GET session

Returns a session object.

Systems

Request

curl 'https://api.meteocontrol.de/v2/systems'

<?php
    /** @var System[] $systems */
    $systems = $api->systems()->get();

Response

{
  "data": [
    {
      "name": "meteocontrol PV system",
      "key": "ABCDE"
    },
    {
      "name": "meteocontrol PV system #2",
      "key": "VWXYZ"
    }
  ]
}

<?php
    /** @var System[] $systems */
    echo $systems[0]->key;// ABCDE
    echo $systems[0]->name;// meteocontrol PV system

GET systems

Returns an array of system objects.

Abbreviations

Abbreviations are uppercase strings that identify datapoints. Common abbreviations on portfolio level are E_Z_EVU (production), G_M (POA irradiance), PR (performance ratio), CO2 (carbon emission) and POWER (system capacity).

Get all abbreviations

Request

curl 'https://api.meteocontrol.de/v2/systems/abbreviations'

<?php
    /** @var string[] $abbreviations */
    $abbreviations = $api->systems()->abbreviations()->get();

Response

{
  "data": [
    "E_Z_EVU",
    "G_M",
    "PR",
    "CO2",
    "POWER",
    "E_N"
  ]
}

<?php
    /** @var string[] $abbreviations */
    echo $abbreviations[0]; // E_Z_EVU
    echo $abbreviations[1]; // G_M
    echo $abbreviations[2]; // PR
    echo $abbreviations[3]; // CO2
    echo $abbreviations[4]; // POWER
    echo $abbreviations[5]; // E_N

GET systems/abbreviations

Returns a list of all available abbreviations.

Get all available measurements

Request

curl 'https://api.meteocontrol.de/v2/systems/abbreviations/E_Z_EVU/measurements?from=2016-11-01T00:00:00+02:00&to=2016-11-01T23:59:59+02:00'

<?php
    $measurementsCriteria = (new MeasurementsCriteria())
        ->withDateFrom(DateTime::createFromFormat(DATE_ATOM, '2016-11-01T00:00:00+02:00'))
        ->withDateTo(DateTime::createFromFormat(DATE_ATOM, '2016-11-01T23:59:59+02:00'));
    /** @var Measurement[] $measurements */
    $measurements = $api->systems()->abbreviation('E_Z_EVU')->measurements()->get($measurementsCriteria);

Response

{
  "data": [
    {
      "systemKey": "ABCDE",
      "E_Z_EVU": [
        {
          "timestamp": "2016-11-01T01:00:00+02:00",
          "value": "52.182"
        }
      ]
    },
    {
      "systemKey": "VWXYZ",
      "E_Z_EVU": [
        {
          "timestamp": "2016-11-01T01:00:00+02:00",
          "value": "199.175"
        }
      ]
    }
  ]
}

<?php
    /** @var Measurement[] $measurements */
    echo $measurements[0]->systemKey;// ABCDE
    echo $measurements[0]->E_Z_EVU[0]->timestamp->format(DATE_ATOM);// 2016-11-01T01:00:00+02:00
    echo $measurements[0]->E_Z_EVU[0]->value;// 58.182
    echo $measurements[1]->systemKey;// VWXYZ
    echo $measurements[1]->E_Z_EVU[0]->timestamp->format(DATE_ATOM);// 2016-11-01T01:00:00+02:00
    echo $measurements[1]->E_Z_EVU[0]->value;// 199.175

GET systems/abbreviations/<abbreviationId>/measurements

Returns a list of measurements for given abbreviation ID.

Path parameters

Name	Type	Description
abbreviationId `required`	`string`	Can contain up to 5 comma delimited abbreviation IDs

Query parameters

Name	Type	Description
from `required`¹	`date`ǀ`datetime`	Start date
to `required`¹	`date`ǀ`datetime`	End date
resolution `optional`	(`day`ǀ`month`ǀ`year`)	Defaults to `day`

¹ The maximum time span between from and to varies depending on the resolution as listed below.

Resolution	Maximum time span
day	60 days
month	1 year
year	no limitation

Response

For each system:

Property	Type	Description
timestamp `fixed`	`datetime`	Timestamp
value `fixed`	`number`	Value

System

Get one system object

Request

curl 'https://api.meteocontrol.de/v2/systems/ABCDE'

<?php
    /** @var SystemDetail $system */
    $system = $api->system('ABCDE')->get();

Response

{
  "data": {
    "name": "meteocontrol PV system",
    "address": {
      "city": "Augsburg",
      "country": "DE",
      "postalCode": "86157",
      "street": "Spicherer Straße 48"
    },
    "elevation": 480,
    "commissionDate": "2016-01-28",
    "coordinates": {
      "latitude": 48.3670191,
      "longitude": 10.8681
    },
    "timezone": {
      "name": "Europe/Berlin",
      "utcOffset": "+01:00"
    },
    "currency": "EUR",
    "hasSolarForecast": false,
    "simulationMethod": "pr",
    "additionalInformation": null
  }
}

<?php
    /** @var SystemDetail $system */
    echo $system->name;// meteocontrol PV system
    echo $system->address->city;// Augsburg
    echo $system->address->country;// DE
    echo $system->address->postalCode;// 86157"
    echo $system->address->street;// Spicherer Straße 48
    echo $system->elevation;// 400
    echo $system->commissionDate->format('Y-m-d');// 2016-01-28
    echo $system->coordinates->latitude;// 48.3670191
    echo $system->coordinates->longitude;// 10.8681
    echo $system->timezone->name;// Europe/Berlin
    echo $system->timezone->utcOffset;// +01:00
    echo $system->currency;// EUR
    echo $system->hasSolarForecast;// false
    echo $system->simulationMethod;// pr
    echo $system->additionalInformation;// null

GET systems/<systemKey>

Returns a system object.

Path parameters

Name	Type	Description
systemKey `required`	`string`	Identification key of the system

Technical data

Request

curl 'https://api.meteocontrol.de/v2/systems/ABCDE/technical-data'

<?php
    /** @var TechnicalData $technicalData */
    $technicalData = $api->system('ABCDE')->technicalData()->get();

Response

{
  "data": {
    "nominalPower": 79.24,
    "siteArea": 549.11,
    "panels": [
      {
        "vendor": "Suntech",
        "model": "STP280-24/Vb",
        "count": 283
      }
    ],
    "inverters": [
      {
        "vendor": "KACO new energy",
        "model": "Powador 8000xi",
        "count": 9
      },
      {
        "vendor": "KACO new energy",
        "model": "Powador 3500xi",
        "count": 1
      }
    ],
    "systemConfigurations": [
      {
        "inverter": {
          "vendor": "KACO new energy",
          "model": "Powador 8000xi",
          "count": 3
        },
        "mpptCount": 3,
        "numberOfModules": 230,
        "mpptInputs": {
          "1": {
            "module": {
              "vendor": "Suntech",
              "model": "STP280-24/Vb"
            },
            "type": "facade",
            "modulesPerString": 40,
            "stringCount": 2
          },
          "2": {
            "module": {
              "vendor": "Suntech",
              "model": "STP280-24/Vb"
            },
            "type": "facade",
            "modulesPerString": 30,
            "stringCount": 3
          },
          "3": {
            "module": {
              "vendor": "Suntech",
              "model": "STP280-24/Vb"
            },
            "type": "facade",
            "modulesPerString": 60,
            "stringCount": 1
          }
        }
      },
      {
        "inverter": {
          "vendor": "KACO new energy",
          "model": "Powador 3500xi",
          "count": 1
        },
        "mpptCount": 1,
        "numberOfModules": 43,
        "mpptInputs": {
          "5": {
            "module": {
              "vendor": "Suntech",
              "model": "STP280-24/Vb"
            },
            "type": "ground",
            "modulesPerString": 43,
            "stringCount": 1
          }
        }
      }
    ]
  }
}

<?php
    /** @var TechnicalData $technicalData */
    echo $technicalData->nominalPower;// 79.24
    echo $technicalData->siteArea;// 549.11
    echo $technicalData->panels[0]->vendor;// Suntech
    echo $technicalData->panels[0]->model;// STP280-24/Vb
    echo $technicalData->panels[0]->count;// 283

    echo $technicalData->inverters[0]->vendor;// KACO new energy
    echo $technicalData->inverters[0]->model;// Powador 8000xi
    echo $technicalData->inverters[0]->count;// 9
    echo $technicalData->inverters[1]->vendor;// KACO new energy
    echo $technicalData->inverters[1]->model;// Powador 3500xi
    echo $technicalData->inverters[1]->count;// 1

    echo $technicalData->systemConfigurations[0]->inverter->vendor;// KACO new energy
    echo $technicalData->systemConfigurations[0]->inverter->model;// Powador 8000xi
    echo $technicalData->systemConfigurations[0]->inverter->count;// 3
    echo $technicalData->systemConfigurations[0]->mpptCount;// 3
    echo $technicalData->systemConfigurations[0]->numberOfModules;// 230
    echo $technicalData->systemConfigurations[0]->mpptInputs[1]->module->vendor;// Suntech
    echo $technicalData->systemConfigurations[0]->mpptInputs[1]->module->model;// STP280-24/Vb
    echo $technicalData->systemConfigurations[0]->mpptInputs[1]->type;// facade
    echo $technicalData->systemConfigurations[0]->mpptInputs[1]->modulesPerString;// 40
    echo $technicalData->systemConfigurations[0]->mpptInputs[1]->stringCount;// 2

GET systems/<systemKey>/technical-data

Path parameters

Name	Type	Description
systemKey `required`	`string`	Identification key of the system

Response

Property	Type	Description
nominalPower `fixed`	`number`	Unit: kWp
siteArea `fixed`	`number`	Unit: m²
panels `fixed`	`array`	Array of Panel
inverters `fixed`	`array`	Array of InverterType
systemConfigurations `fixed`	`array`	Array of SystemConfiguration

Panel

Property	Type	Description
vendor `fixed`	`string`ǀ`null`	Vendor
model `fixed`	`string`	Model
count `fixed`	`integer`	Number of panels

InverterType

Property	Type	Description
vendor `fixed`	`string`ǀ`null`	Vendor
model `fixed`	`string`ǀ`null`	Model
count `fixed`	`integer`	Number of inverters

SystemConfiguration

Property	Type	Description
inverter `fixed`	InverterType
mpptCount `fixed`	`integer`	Number of mppt count
numberOfModules `fixed`	`integer`	Number of modules
mpptInputs `fixed`	`array`	Array of MpptInput

MpptInput

Property	Type	Description
module `fixed`	PanelModule
type `fixed`	`string`	Type of installation¹
modulesPerString `fixed`	`integer`	Number of modules connected in one string
stringCount `fixed`	`integer`	Number of parallel-connected string

PanelModule

Property	Type	Description
vendor `fixed`	`string`	Vendor
model `fixed`	`string`	Model

¹ Type of installation

Value	Description
ground	Ground installation
roofTopGreatDistance	Roof top installation, great distance (>10cm)
roofTopSmallDistance	Roof top installation, small distance (<10cm)
roofIntegration	Roof integration
facade	Façade
flatRoof	Flat-roof installation (elevated)

Last data input

Get timestamp of last data input

Request

curl 'https://api.meteocontrol.de/v2/systems/ABCDE/technical-data/last-data-input'

<?php
    /** @var LastDataInput $lastDataInput */
    $lastDataInput = $api->system('ABCDE')->technicalData()->lastDataInput()->get();

Response

{
  "data": {
    "timestamp": "2024-08-06T12:59:59+00:00"
  }
}

<?php
    /** @var LastDataInput $lastDataInput */
    echo $lastDataInput->timestamp->format(DATE_ATOM);// 2024-08-06T12:59:59+00:00

GET systems/<systemKey>/technical-data/last-data-input

Path parameters

Name	Type	Description
systemKey `required`	`string`	Identification key of the system

Response

Property	Type	Description
timestamp `fixed`	`datetime`ǀ`null`	Last data input timestamp in UTC timezone

Virtual meters

Get all virtual meters

Request

curl 'https://api.meteocontrol.de/v2/systems/ABCDE/virtual-meters'

<?php
    /** @var VirtualMeter[] $virtualMeters */
    $virtualMeters = $api->system('ABCDE')->virtualMeters()->get();

Response

{
  "data": [
    {
      "id": "1",
      "name": "Virtual meter 1",
      "serial": "serial.1"
    },
    {
      "id": "2",
      "name": "Virtual meter 2",
      "serial": "serial.2"
    }
  ]
}

<?php
    /** @var VirtualMeter[] $virtualMeters */
    echo $virtualMeters[0]->id;// 1
    echo $virtualMeters[0]->name;// Virtual meter 1
    echo $virtualMeters[0]->serial;// serial.1
    echo $virtualMeters[1]->id;// 2
    echo $virtualMeters[1]->name;// Virtual meter 2
    echo $virtualMeters[1]->serial;// serial.2

GET systems/<systemKey>/virtual-meters

Path parameters

Name	Type	Description
systemKey `required`	`string`	Identification key of the system

Response

Property	Type	Description
id `fixed`	`string`	Virtual meter device ID
name `fixed`	`string`	Customized name
serial `fixed`	`string`	Serial number

Get single virtual meter

Request

curl 'https://api.meteocontrol.de/v2/systems/ABCDE/virtual-meters/1'

<?php
    /** @var VirtualMeterDetail $virtualMeter */
    $virtualMeter = $api->system('ABCDE')->virtualMeter('1')->get();

Response

{
  "data": {
    "id": "1",
    "name": "Virtual meter 1",
    "serial": "serial.1",
    "installationDate": "2019-11-11",
    "unit": "kWh"
  }
}

<?php
    /** @var VirtualMeterDetail $virtualMeter */
    echo $virtualMeter->id;// 1
    echo $virtualMeter->name;// Virtual meter 1
    echo $virtualMeter->serial;// serial.1
    echo $virtualMeter->installationDate->format('Y-m-d');// 2019-11-11
    echo $virtualMeter->unit;// kWh

GET systems/<systemKey>/virtual-meters/<deviceId>

Path parameters

Name	Type	Description
systemKey `required`	`string`	Identification key of the system
deviceId `required`	`string`	Virtual meter device ID

Response

Property	Type	Description
id `fixed`	`string`	Virtual meter device ID
name `fixed`	`string`	Customized name
serial `fixed`	`string`	Serial number
installationDate `fixed`	`string`	Installation date
unit `fixed`	`string`	Unit

Readings

Get latest reading

Request

curl 'https://api.meteocontrol.de/v2/systems/ABCDE/virtual-meters/1/readings'

<?php
    $meterReadingCriteria = new MeterReadingCriteria();
    /** @var VirtualMeterReading $readings */
    $readings = $api->system('ABCDE')->virtualMeter(1)->readings()->get($meterReadingCriteria);

Response

{
  "data": [
    {
      "id": 7777,
      "type": "MANUAL",
      "timestamp": "2019-11-11T18:00:00+02:00",
      "value": 30
    }
  ]
}

<?php
    /** @var VirtualMeterReading[] $readings */
    echo $readings[0]->id;// 7777
    echo $readings[0]->type;// MANUAL
    echo $readings[0]->timestamp->format(DATE_ATOM);// 2019-11-11T18:00:00+02:00
    echo $readings[0]->value;// 30

GET systems/<systemKey>/virtual-meters/<deviceId>/readings

Path parameters

Name	Type	Description
systemKey `required`	`string`	Identification key of the system
deviceId `required`	`string`	Virtual meter device ID

Query parameters

Name	Type	Description
type `optional`	(`all`ǀ`auto`ǀ`manual`)	Defaults to `all`

Response

Property	Type	Description
id `fixed`	`integer`	Reading ID
type `fixed`	`string`	Reading type
timestamp `fixed`	`datetime`	Timestamp
value `fixed`	`number`	Value

Get readings

Request

curl 'https://api.meteocontrol.de/v2/systems/ABCDE/virtual-meters/1/readings?from=2018-02-28T00:00:00+02:00&to=2018-02-28T23:59:59+02:00&type=all'

<?php
    $meterReadingCriteria = (new MeterReadingCriteria())
        ->withDateFrom(DateTime::createFromFormat(DATE_ATOM, '2018-02-28T00:00:00+02:00'))
        ->withDateTo(DateTime::createFromFormat(DATE_ATOM, '2018-02-28T23:59:59+02:00'))
        ->withType(MeterReadingCriteria::READING_TYPE_ALL);
    /** @var VirtualMeterReading $readings */
    $readings = $api->system('ABCDE')->virtualMeter(1)->readings()
        ->get($meterReadingCriteria);

Response

{
  "data": [
    {
      "id": 146803853,
      "type": "MANUAL",
      "timestamp": "2018-02-28T23:59:59+01:00",
      "value": 3698.2216528918002
    },
    {
      "id": 146803854,
      "type": "AUTO",
      "timestamp": "2018-03-31T23:59:59+02:00",
      "value": 3958.0235319860999
    },
    {
      "id": 146803855,
      "type": "MANUAL",
      "timestamp": "2018-04-30T23:59:59+02:00",
      "value": 4294.8163073654996
    }
  ]
}

<?php
    /** @var VirtualMeterReading[] $readings */
    echo $readings[0]->id;// 146803853
    echo $readings[0]->type;// MANUAL
    echo $readings[0]->timestamp->format(DATE_ATOM);// 2018-02-28T23:59:59+01:00
    echo $readings[0]->value;// 3698.2216528918002
    echo $readings[1]->id;// 146803854
    echo $readings[1]->type;// AUTO
    echo $readings[1]->timestamp->format(DATE_ATOM);// 2018-03-31T23:59:59+02:00
    echo $readings[1]->value;// 3958.0235319860999

GET systems/<systemKey>/virtual-meters/<deviceId>/readings

Path parameters

Name	Type	Description
systemKey `required`	`string`	Identification key of the system
deviceId `required`	`string`	Virtual meter device ID

Query parameters

Name	Type	Description
from `required`¹	`date`ǀ`datetime`	Start date
to `required`¹	`date`ǀ`datetime`	End date
type `optional`	(`all`ǀ`auto`ǀ`manual`)	Defaults to `all`

¹ The maximum time span between from and to is limited to 1 year.

Response

Property	Type	Description
id `fixed`	`integer`	Reading ID
type `fixed`	`string`	Reading type
timestamp `fixed`	`datetime`	Timestamp
value `fixed`	`number`	Value

Bulk

Request

curl 'https://api.meteocontrol.de/v2/systems/ABCDE/bulk/measurements?from=2016-09-01T10:00:00+02:00&to=2016-09-01T10:15:00+02:00'

<?php
    $measurementsCriteria = (new MeasurementsCriteria())
        ->withDateFrom(DateTime::createFromFormat(DATE_ATOM, '2016-09-01T10:00:00+02:00'))
        ->withDateTo(DateTime::createFromFormat(DATE_ATOM, '2016-09-01T10:15:00+02:00'));
    /** @var MeasurementsBulkReader $bulkData */
    $bulkData = $api->system('ABCDE')->bulk()->measurements()->get($measurementsCriteria);

Response

{
  "basics":{
    "2016-09-01T10:15:00+02:00":{
      "E_Z_EVU": 502
    },
    "2016-09-01T10:30:00+02:00":{
      "E_Z_EVU": 548
    }
  },
  "calculations":{
    "2016-09-01T00:00:00+02:00":{
      "POWER": 100,
      "PR": 100.25
    }
  },
  "inverters": {
    "2016-09-01T10:15:00+02:00": {
      "Id32302.7": {
        "P_AC": 454.34
      },
      "Id32302.8": {
        "P_AC": 452.34
      }
    },
    "2016-09-01T10:30:00+02:00": {
      "Id32302.7": {
        "P_AC": 455.34
      },
      "Id32302.8": {
        "P_AC": 451.34
      }
    }
  },
  "meters": {
    "2016-09-01T10:15:00+02:00": {
      "12345": {
          "M_AC_E_EXP": 7127.4
      },
      "12346": {
          "M_AC_E_EXP": 872.6
      }
    },
    "2016-09-01T10:30:00+02:00": {
      "12345": {
          "M_AC_E_EXP": 7130.4
      },
      "12346": {
          "M_AC_E_EXP": 870.6
      }
    }
  },
  "sensors": {
    "2016-09-01T10:15:00+02:00": {
      "12345": {
        "SRAD": 7.23
      },
      "12346": {
        "SRAD": 7.14
      }
    },
    "2016-09-01T10:30:00+02:00": {
      "12345": {
        "SRAD": 7.1
      },
      "12346": {
        "SRAD": 7.04
      }
    }
  },
  "stringboxes": {
    "2016-09-01T10:15:00+02:00": {
      "12345": {
        "I1": 3.449
      },
      "12346": {
        "I1": 3.913
      }
    },
    "2016-09-01T10:30:00+02:00": {
      "12345": {
        "I1": 3.449
      },
      "12346": {
        "I1": 3.869
      }
    }
  },
  "batteries": {
    "2016-09-01T10:15:00+02:00": {
      "145146": {
        "B_CHARGE_LEVEL": 193.08199999999999,
        "B_E_EXP": 1460.0820000000001,
        "B_E_IMP": 141.476,
        "T1": 143.10900000000001
      },
      "145147": {
        "B_CHARGE_LEVEL": 193.09200000000001,
        "B_E_EXP": 1460.0920000000001,
        "B_E_IMP": 141.48599999999999,
        "T1": 143.119
      }
    },
    "2016-09-01T10:30:00+02:00": {
      "145146": {
        "B_CHARGE_LEVEL": 193.102,
        "B_E_EXP": 1460.1020000000001,
        "B_E_IMP": 141.49600000000001,
        "T1": 143.12899999999999
      },
      "145147": {
        "B_CHARGE_LEVEL": 193.11199999999999,
        "B_E_EXP": 1460.1120000000001,
        "B_E_IMP": 141.506,
        "T1": 143.13900000000001
      }
    }
  },
  "ppcs": {
    "2016-09-01T10:15:00+02:00": {
      "163784": {
        "PPC_P_AC_INV": 72.200000000000003,
        "PPC_P_AC_AVAIL": 37.450000000000003,
        "PPC_Q_AC_AVAIL": 32.299999999999997,
        "PPC_P_SET_GRIDOP_REL": 52.299999999999997,
        "PPC_P_SET_GRIDOP_ABS": 85.299999999999997,
        "PPC_P_SET_RPC_REL": 1.3999999999999999,
        "PPC_P_SET_REL": 77.400000000000006,
        "PPC_PF_SET": null,
        "PPC_Q_SET_ABS": 85.900000000000006,
        "PPC_P_AC_GRIDOP_MAX": 42.770000000000003,
        "PPC_P_AC_RPC_MAX": 35.140000000000001,
        "PPC_P_AC": 42.43,
        "PPC_Q_AC": 91.590000000000003,
        "PPC_PF": 8.3000000000000007,
        "PPC_Q_SET_REL": 39.100000000000001
      }
    },
    "2016-09-01T10:30:00+02:00": {
      "163784": {
        "PPC_P_AC_INV": 17.059999999999999,
        "PPC_P_AC_AVAIL": 47.579999999999998,
        "PPC_Q_AC_AVAIL": 53.100000000000001,
        "PPC_P_SET_GRIDOP_REL": 13.6,
        "PPC_P_SET_GRIDOP_ABS": 90,
        "PPC_P_SET_RPC_REL": 85.400000000000006,
        "PPC_P_SET_REL": 3.2999999999999998,
        "PPC_PF_SET": 1.2,
        "PPC_Q_SET_ABS": 65.400000000000006,
        "PPC_P_AC_GRIDOP_MAX": 23.960000000000001,
        "PPC_P_AC_RPC_MAX": 76.609999999999999,
        "PPC_P_AC": 62.740000000000002,
        "PPC_Q_AC": 99.480000000000004,
        "PPC_PF": 7.2000000000000002,
        "PPC_Q_SET_REL": null
      }
    }
  }
}

<?php
    /** @var MeasurementsBulkReader $bulkData */
    $bulkDataArray = $bulkData->getAsArray();
    echo $bulkDataArray['basic']['2016-09-01T10:15:00+02:00']['E_Z_EVU'];// 502
    echo $bulkDataArray['calculations']['2016-09-01T00:00:00+02:00']['POWER'];// 100
    echo $bulkDataArray['inverters']['2016-09-01T10:15:00+02:00']['Id32302.7']['P_AC'];// 454.34
    echo $bulkDataArray['meters']['2016-09-01T10:15:00+02:00']['12345']['M_AC_E_EXP'];// 7127.4
    echo $bulkDataArray['sensors']['2016-09-01T10:15:00+02:00']['12345']['SRAD'];// 7.23
    echo $bulkDataArray['stringboxes']['2016-09-01T10:15:00+02:00']['12345']['I1'];// 3.449

GET systems/<systemKey>/bulk/measurements

Path parameters

Name	Type	Description
systemKey `required`	`string`	Identification key of the system

Query parameters

Name	Type	Description
from `required`¹	`date`ǀ`datetime`	Start date
to `required`¹	`date`ǀ`datetime`	End date
format `optional`	`json`ǀ`csv`	Export format, defaults to `json`
resolution `optional`	(`minute²`ǀ`interval`ǀ`fifteen-minutes`ǀ`thirty-minutes`ǀ`hour`ǀ`day`)	Defaults to `interval`
deviceIds `optional`	`string`	Comma separated deviceIds
abbreviations `optional`	`string`	Comma separated abbreviations
includeInterval `optional`³	`integer` `0`ǀ`1`	Defaults to `0`

¹ The maximum time span is 24 hours between from and to.
² The option minute resolution is only supported by meteocontrol blue'Log XM / XC (Firmware 2.0 and higher)
³ Only for interval resolution

Options for CSV format

The following query parameters are valid only if format is csv
For response example in CSV format, please check HERE.

Name	Type	Description
delimiter	`comma`ǀ`semicolon`ǀ`colon`ǀ`tab`	The delimiter, defaults to `comma`
lineBreak	`LF`ǀ`CR`ǀ`CR/LF`	The line breaks, defaults to `LF`
decimalPoint	`dot`ǀ`comma`	The decimal point, defaults to `dot`
emptyPlaceholder	`text`, empty string by default, any text accepted	The place holder for empty value
precision	`integer`, accepts from 0 to 4	The decimal precision, defaults to `2`

Basics

Abbreviations

Request

curl 'https://api.meteocontrol.de/v2/systems/ABCDE/basics/abbreviations'

<?php
    /**  @var string[] $abbreviations */
    $abbreviations = $api->system('ABCDE')->basics()->abbreviations()->get();

Response

{
  "data": [
    "E_Z_PV1",
    "E_Z_EVU",
    "G_M0"
  ]
}

<?php
    /**  @var string[] $abbreviations */
    echo $abbreviations[0];// E_Z_PV1
    echo $abbreviations[1];// E_Z_EVU
    echo $abbreviations[2];// G_M0

GET systems/<systemKey>/basics/abbreviations

Returns a list of abbreviation IDs for the basic information of a system. Common abbreviations within the basics endpoint are E_Z_EVU (production) or G_M0 (POA irradiance).

Path parameters

Name	Type	Description
systemKey `required`	`string`	Identification key of the system

Get single abbreviation

Request

curl 'https://api.meteocontrol.de/v2/systems/ABCDE/basics/abbreviations/E_Z_EVU'

<?php
    /**  @var Abbreviation $abbreviation */
    $abbreviation = $api->system('ABCDE')->basics()->abbreviation('E_Z_EVU')->get();

Response

{
  "data": {
    "aggregation": "SUM",
    "precision": null,
    "description": "PV Production",
    "unit": "kWh"
  }
}

<?php
    /**  @var Abbreviation $abbreviation */
    echo $abbreviation->aggregation;// SUM
    echo $abbreviation->precision;// null
    echo $abbreviation->description;// PV Production
    echo $abbreviation->unit;// kWh

GET systems/<systemKey>/basics/abbreviations/<abbreviationId>

Returns an information object of an abbreviation.

Path parameters

Name	Type	Description
systemKey `required`	`string`	Identification key of the system
abbreviationId `required`	`string`	Abbreviation ID

Response

Information object

Property	Type	Description
aggregation `fixed`	(`SUM`ǀ`AVG`ǀ`MAX`)	Aggregation method when requesting other resolutions than interval
precision `fixed`	`integer`	Number of decimal places
description `fixed`	`string`	Description
unit `fixed`	`string`	Unit

Measurements

Request

curl 'https://api.meteocontrol.de/v2/systems/ABCDE/basics/abbreviations/E_Z_EVU/measurements?from=2016-11-01T00:00:00+02:00&to=2016-11-01T00:05:00+02:00'

<?php
    $measurementsCriteria = (new MeasurementsCriteria())
        ->withDateFrom(DateTime::createFromFormat(DATE_ATOM, '2016-11-01T00:00:00+02:00'))
        ->withDateTo(DateTime::createFromFormat(DATE_ATOM, '2016-11-01T00:05:00+02:00'));
    /** @var MeasurementValue[] $measurements */
    $measurements = $api->system('ABCDE')->basics()->abbreviation('E_Z_EVU')->measurements()
        ->get($measurementsCriteria);

Response

{
  "data": {
    "E_Z_EVU": [
      {
        "timestamp": "2016-11-01T00:00:00+02:00",
        "value": 0
      },
      {
        "timestamp": "2016-11-01T00:05:00+02:00",
        "value": 0
      }
    ]
  }
}

<?php
    /** @var DevicesMeasurement $measurements */
    $measurement = $measurements['E_Z_EVU'];
    echo $measurements[0]->timestamp->format(DATE_ATOM);// 2016-11-01T00:00:00+02:00
    echo $measurements[0]->value;// 0
    echo $measurements[1]->timestamp->format(DATE_ATOM);// 2016-11-01T00:05:00+02:00
    echo $measurements[1]->value;// 0

GET systems/<systemKey>/basics/abbreviations/<abbreviationId>/measurements

Returns an array of measurements objects.

Path parameters

Name	Type	Description
systemKey `required`	`string`	Identification key of the system
abbreviationId `required`	`string`	Can contain up to 5 comma delimited abbreviation IDs

Query parameters

Name	Type	Description
from `required`¹	`date`ǀ`datetime`	Start date
to `required`¹	`date`ǀ`datetime`	End date
resolution `optional`	(`interval`ǀ`fifteen-minutes`ǀ`thirty-minutes`ǀ`hour`ǀ`day`ǀ`month`ǀ`year`)	Defaults to `interval`
includeInterval `optional`²	`integer` `0`ǀ`1`	Defaults to `0`

¹ The maximum time span between from and to varies depending on the resolution as listed below.

Resolution	Maximum time span
interval	31 days
fifteen-minutes	31 days
thirty-minutes	31 days
hour	31 days
day	60 days
month	1 year
year	no limitation

² Only for interval resolution

Response

Measurement object

Property	Type	Description
timestamp `fixed`	`datetime`	Timestamp
value `fixed`	`number`	Value
interval `optional`	`number`	Interval, in seconds

Bulk

Request

curl 'https://api.meteocontrol.de/v2/systems/ABCDE/basics/bulk/measurements?from=2016-11-01T10:00:00+02:00&to=2016-11-01T10:05:00+02:00'

<?php
    $measurementsCriteria = (new MeasurementsCriteria())
        ->withDateFrom(DateTime::createFromFormat(DATE_ATOM, '2016-11-01T10:00:00+02:00'))
        ->withDateTo(DateTime::createFromFormat(DATE_ATOM, '2016-11-01T10:05:00+02:00'));
    /** @var MeasurementsBulkReader $bulkData */
    $bulkData = $api->system('ABCDE')->basics()->bulk()->measurements()->get($measurementsCriteria);

Response

{
  "2016-11-01T10:00:00+02:00": {
    "G_M0": 501.5,
    "E_Z_EVU": 1103
  },
  "2016-11-01T10:05:00+02:00": {
    "G_M0": 548.5,
    "E_Z_EVU": 1178
  }
}

<?php
    /** @var MeasurementsBulkReader $bulkData */
    $bulkDataArray = $bulkData->getAsArray();
    echo $bulkDataArray['2016-11-01T10:00:00+02:00']['G_M0'];// 501.5
    echo $bulkDataArray['2016-11-01T10:00:00+02:00']['E_Z_EVU'];// 1103
    echo $bulkDataArray['2016-11-01T10:05:00+02:00']['G_M0'];// 548.5
    echo $bulkDataArray['2016-11-01T10:05:00+02:00']['E_Z_EVU'];// 1178

GET systems/<systemKey>/basics/bulk/measurements

Path parameters

Name	Type	Description
systemKey `required`	`string`	Identification key of the system

Query parameters

Name	Type	Description
from `required`¹	`date`ǀ`datetime`	Start date
to `required`¹	`date`ǀ`datetime`	End date
format `optional`	`json`ǀ`csv`	Export format, defaults to `json`
abbreviations `optional`	`string`	Comma separated abbreviations
includeInterval `optional`	`integer` `0`ǀ`1`	Defaults to `0`

¹ The maximum time span is 24 hours between from and to.

Options for CSV format

The following query parameters are valid only if format is csv
For response example in CSV format, please check HERE.

Name	Type	Description
delimiter	`comma`ǀ`semicolon`ǀ`colon`ǀ`tab`	The delimiter, defaults to `comma`
lineBreak	`LF`ǀ`CR`ǀ`CR/LF`	The line breaks, defaults to `LF`
decimalPoint	`dot`ǀ`comma`	The decimal point, defaults to `dot`
emptyPlaceholder	`text`, empty string by default, any text accepted	The place holder for empty value
precision	`integer`, accepts from 0 to 4	The decimal precision, defaults to `2`

Calculations

Abbreviations

Request

curl 'https://api.meteocontrol.de/v2/systems/ABCDE/calculations/abbreviations'

<?php
    /** @var string[] $abbreviations */
    $abbreviations = $api->system('ABCDE')->calculations()->abbreviations()->get();

Response

{
  "data": [
    "E_N",
    "PR",
    "VFG"
  ]
}

<?php
    /**  @var string[] $abbreviations */
    echo $abbreviations[0];// E_N
    echo $abbreviations[1];// PR
    echo $abbreviations[2];// VFG

GET systems/<systemKey>/calculations/abbreviations

Returns a list of abbreviation IDs. Common abbreviations within the calculations endpoint are E_N (normalized production), PR (Performance Ratio) or VFG (Availability).

Path parameters

Name	Type	Description
systemKey `required`	`string`	Identification key of the system

Get single abbreviation

Request

curl 'https://api.meteocontrol.de/v2/systems/ABCDE/calculations/abbreviations/PR'

<?php
    /** @var Abbreviation $abbreviation */
    $abbreviation = $api->system('ABCDE')->calculations()->abbreviation('PR')->get();

Response

{
  "data": {
    "aggregation": "AVG",
    "precision": 2,
    "description": "Performance ratio",
    "unit": "%"
  }
}

<?php
    /** @var Abbreviation $abbreviation */
    echo $abbreviation->aggregation;// AVG
    echo $abbreviation->description;// 2
    echo $abbreviation->precision;// Performance ratio
    echo $abbreviation->unit;// %

GET systems/<systemKey>/calculations/abbreviations/<abbreviationId>

Returns an information object for an abbreviation.

Path parameters

Name	Type	Description
systemKey `required`	`string`	Identification key of the system
abbreviationId `required`	`string`	Abbreviation ID

Response

Information object

Property	Type	Description
aggregation `fixed`	(`SUM`ǀ`AVG`ǀ`MAX`)	Aggregation method when requesting other resolutions than interval
precision `fixed`	`integer`	Number of decimal places
description `fixed`	`string`	Description
unit `fixed`	`string`	Unit

Measurements

Request

curl 'https://api.meteocontrol.de/v2/systems/ABCDE/calculations/abbreviations/E_N/measurements?from=2016-10-01T00:00:00+02:00&to=2016-10-01T00:05:00+02:00'

<?php
    $measurementsCriteria = (new MeasurementsCriteria())
        ->withDateFrom(DateTime::createFromFormat(DATE_ATOM, '2016-10-01T00:00:00+02:00'))
        ->withDateTo(DateTime::createFromFormat(DATE_ATOM, '2016-10-01T00:05:00+02:00'));
    /** @var MeasurementValue[] $measurements */
    $measurements = $api->system('ABCDE')->calculations()->abbreviation('E_N')->measurements()
        ->get($measurementsCriteria);

Response

{
  "data": {
    "E_N": [
      {
        "timestamp": "2016-10-01T00:00:00+02:00",
        "value": 0
      },
      {
        "timestamp": "2016-10-01T00:05:00+02:00",
        "value": 0
      }
    ]
  }
}

<?php
    /** @var DevicesMeasurement $measurements */
    $measurement = $measurements['E_N'];
    echo $measurement[0]->timestamp->format(DATE_ATOM);// 2016-10-01T00:00:00+02:00
    echo $measurement[0]->value;// 0
    echo $measurement[1]->timestamp->format(DATE_ATOM);// 2016-10-01T00:05:00+02:00
    echo $measurement[1]->value;// 0

GET systems/<systemKey>/calculations/abbreviations/<abbreviationId>/measurements

Returns an array of measurements objects.

Path parameters

Name	Type	Description
systemKey `required`	`string`	Identification key of the system
abbreviationId `required`	`string`	Can contain up to 5 comma delimited abbreviation IDs

Query parameters

Name	Type	Description
from `required`¹	`date`ǀ`datetime`	Start date
to `required`¹	`date`ǀ`datetime`	End date
resolution `optional`	(`day`ǀ`month`ǀ`year`)	Defaults to `day`

¹ The maximum time span between from and to varies depending on the resolution as listed below.

Resolution	Maximum time span
day	60 days
month	1 year
year	no limitation

Response

Measurement object

Property	Type	Description
timestamp `fixed`	`datetime`	Timestamp
value `fixed`	`number`	Value

Bulk

Request

curl 'https://api.meteocontrol.de/v2/systems/ABCDE/calculations/bulk/measurements?from=2016-09-01T23:45:00+02:00&to=2016-09-01T23:59:59+02:00'

<?php
    $measurementsCriteria = (new MeasurementsCriteria())
        ->withDateFrom(DateTime::createFromFormat(DATE_ATOM, '2016-09-01T23:45:00+02:00'))
        ->withDateTo(DateTime::createFromFormat(DATE_ATOM, '2016-09-01T23:59:59+02:00'));
    /** @var MeasurementsBulkReader $bulkData */
    $bulkData = $api->system('ABCDE')->calculations()->bulk()->measurements()->get($measurementsCriteria);

Response

{
   "2016-09-01T00:00:00+02:00": {
     "AREA": 66607.58,
     "CO2": 143.31,
     "E_MEAN_DEV": null,
     "E_MESS": 44579,
     "E_N": null,
     "E_ZAEHLER": 44579,
     "EPI": null,
     "POWER": 9990.12,
     "PR": 82.277446881595,
     "SOLIDX": null,
     "VFG": 100
   }
}

<?php
    /** @var MeasurementsBulkReader $bulkData */
    $bulkDataArray = $bulkData->getAsArray();
    echo $bulkDataArray['2016-09-01T00:00:00+02:00']['AREA'];// 66607.58
    echo $bulkDataArray['2016-09-01T00:00:00+02:00']['CO2'];// 143.31
    echo $bulkDataArray['2016-09-01T00:00:00+02:00']['E_MEAN_DEV'];// null
    echo $bulkDataArray['2016-09-01T00:00:00+02:00']['E_MESS'];// 44579
    echo $bulkDataArray['2016-09-01T00:00:00+02:00']['E_N'];// null
    echo $bulkDataArray['2016-09-01T00:00:00+02:00']['E_ZAEHLER'];// 44579
    echo $bulkDataArray['2016-09-01T00:00:00+02:00']['EPI'];// null
    echo $bulkDataArray['2016-09-01T00:00:00+02:00']['POWER'];// 9990.12
    echo $bulkDataArray['2016-09-01T00:00:00+02:00']['PR'];// 82.277446881595
    echo $bulkDataArray['2016-09-01T00:00:00+02:00']['SOLIDX'];// null
    echo $bulkDataArray['2016-09-01T00:00:00+02:00']['VFG'];// 100

GET systems/<systemKey>/calculations/bulk/measurements

Path parameters

Name	Type	Description
systemKey `required`	`string`	Identification key of the system

Query parameters

Name	Type	Description
from `required`¹	`date`ǀ`datetime`	Start date
to `required`¹	`date`ǀ`datetime`	End date
format `optional`	`json`ǀ`csv`	Export format, defaults to `json`
abbreviations `optional`	`string`	Comma separated abbreviations

¹ The maximum time span is 24 hours between from and to.

Options for CSV format

The following query parameters are valid only if format is csv
For response example in CSV format, please check HERE.

Name	Type	Description
delimiter	`comma`ǀ`semicolon`ǀ`colon`ǀ`tab`	The delimiter, defaults to `comma`
lineBreak	`LF`ǀ`CR`ǀ`CR/LF`	The line breaks, defaults to `LF`
decimalPoint	`dot`ǀ`comma`	The decimal point, defaults to `dot`
emptyPlaceholder	`text`, empty string by default, any text accepted	The place holder for empty value
precision	`integer`, accepts from 0 to 4	The decimal precision, defaults to `2`

Simulation

Get currently activated simulation value

Request

curl 'https://api.meteocontrol.de/v2/systems/ABCDE/calculations/simulation?from=2021-02-01T00:00:00+01:00&to=2021-02-01T23:59:59+01:00&considerPowerControl=true'

<?php
    $measurementsCriteria = (new MeasurementsCriteria())
        ->withDateFrom(DateTime::createFromFormat(DATE_ATOM, '2021-02-01T00:00:00+01:00'))
        ->withDateTo(DateTime::createFromFormat(DATE_ATOM, '2021-02-01T23:59:59+01:00'))
        ->withConsiderPowerControl(true);
    /** @var SimulationValue[] $simulation */
    $simulation = $api->system('ABCDE')->calculations()->simulation()->get($measurementsCriteria);

Response

{
  "data": [
    {
      "timestamp": "2021-02-01T00:00:00+01:00",
      "max": 2.79430153178,
      "min": 2.2862467078199997,
      "expected": 2.5402741198
    },
    {
      "timestamp": "2021-02-01T00:05:00+01:00",
      "max": 2.3015888865200007,
      "min": 1.8831181798800003,
      "expected": 2.0923535332000003
    }
  ]
}

<?php
    /** @var SimulationValue[] $simulation */
    echo $simulation[0]->timestamp->format(DATE_ATOM);// 2021-02-01T00:00:00+01:00
    echo $simulation[0]->max;// 2.79430153178
    echo $simulation[0]->min;// 2.2862467078199997
    echo $simulation[0]->expected;// 2.5402741198
    echo $simulation[1]->timestamp->format(DATE_ATOM);// 2021-02-01T00:05:00+01:00
    echo $simulation[1]->max;// 2.3015888865200007
    echo $simulation[1]->min;// 1.8831181798800003
    echo $simulation[1]->expected;// 2.0923535332000003

GET systems/<systemKey>/calculations/simulation

Path parameters

Name	Type	Description
systemKey `required`	`string`	Identification key of the system

Query parameters

Name	Type	Description
from `required`¹	`date`ǀ`datetime`	Start date
to `required`¹	`date`ǀ`datetime`	End date
resolution `optional`	(`interval`ǀ`day`ǀ`month`ǀ`year`)	Defaults to `interval`²
considerPowerControl `optional`	(`true`ǀ`false`)	Power control considered, defaults to `true`

¹ The maximum time span between from and to varies depending on the resolution as listed below.
² If the system has no sensor, the finest available resolution is day.

Resolution	Maximum time span
interval	31 days
day	60 days
month	1 year
year	no limitation

Response

SimulationValue object

Property	Type	Description
timestamp `fixed`	`datetime`	Timestamp
max `fixed`	`number`	Maximum value
min `fixed`	`number`	Minimum value
expected `fixed`	`number`	Expected value

Environmental savings

CO2

Request

curl 'https://api.meteocontrol.de/v2/systems/ABCDE/environmental-savings/co2?from=2022-07-01T00:00:00+02:00&to=2022-07-03T00:00:00+02:00'

<?php
    $criteria = (new MeasurementsCriteria())
        ->withDateFrom(DateTime::createFromFormat(DATE_ATOM, '2022-07-01T00:00:00+02:00'))
        ->withDateTo(DateTime::createFromFormat(DATE_ATOM, '2022-07-03T00:00:00+02:00'));
    /** @var CO2[] $co2Savings */
    $co2Savings = $api->system('ABCDE')->environmentalSavings()->co2()->get($criteria);

Response

{
    "data": [
        {
            "timestamp": "2022-07-01T00:00:00+02:00",
            "value": 3510.13
        },
        {
            "timestamp": "2022-07-02T00:00:00+02:00",
            "value": 537.21
        },
        {
            "timestamp": "2022-07-03T00:00:00+02:00",
            "value": 1502.62
        }
    ]
}

<?php
    /** @var CO2[] $co2Savings */
    echo $co2Savings[0]->timestamp->format(DATE_ATOM);  // '2022-07-01T00:00:00+02:00'
    echo $co2Savings[0]->value; // 3510.13
    echo $co2Savings[1]->timestamp->format(DATE_ATOM);  // '2022-07-02T00:00:00+02:00'
    echo $co2Savings[1]->value; // 537.21
    echo $co2Savings[2]->timestamp->format(DATE_ATOM);  // '2022-07-03T00:00:00+02:00'
    echo $co2Savings[2]->value; // 1502.62

GET systems/<systemKey>/environmental-savings/co2

Returns a list of CO2 savings (in kg).

Path parameters

Name	Type	Description
systemKey `required`	`string`	Identification key of the system

Query parameters

Name	Type	Description
from `optional`¹	`date`ǀ`datetime`	Start date
to `optional`¹	`date`ǀ`datetime`	End date
resolution `optional`²	(`day`ǀ`month`ǀ`year`)	Defaults to `day`

¹ If the parameters from and to are omitted, a list with one aggregated value for the entire lifetime of the system (up to the current date) is returned as the result.
² Use only in combination with the parameters from and to.

Response

Property	Type	Description
timestamp `fixed`	`datetime`	Timestamp
value `fixed`	`number`ǀ`null`	CO2 savings (in kg)

Tree equivalents

Request

curl 'https://api.meteocontrol.de/v2/systems/ABCDE/environmental-savings/tree?from=2022-07-01T00:00:00+02:00&to=2022-07-03T00:00:00+02:00'

<?php
    $criteria = (new MeasurementsCriteria())
        ->withDateFrom(DateTime::createFromFormat(DATE_ATOM, '2022-07-01T00:00:00+02:00'))
        ->withDateTo(DateTime::createFromFormat(DATE_ATOM, '2022-07-03T00:00:00+02:00'));
    /** @var TreeEquivalent[] $treeEquivalents */
    $treeEquivalents = $api->system('ABCDE')->environmentalSavings()->tree()->get($criteria);

Response

{
    "data": [
        {
            "timestamp": "2022-07-01T00:00:00+02:00",
            "value": 333
        },
        {
            "timestamp": "2022-07-02T00:00:00+02:00",
            "value": 51
        },
        {
            "timestamp": "2022-07-03T00:00:00+02:00",
            "value": 142
        }
    ]
}

<?php
    /** @var TreeEquivalent[] $treeEquivalents */
    echo $treeEquivalents[0]->timestamp->format(DATE_ATOM);  // '2022-07-01T00:00:00+02:00'
    echo $treeEquivalents[0]->value; // 333
    echo $treeEquivalents[1]->timestamp->format(DATE_ATOM);  // '2022-07-02T00:00:00+02:00'
    echo $treeEquivalents[1]->value; // 51
    echo $treeEquivalents[2]->timestamp->format(DATE_ATOM);  // '2022-07-03T00:00:00+02:00'
    echo $treeEquivalents[2]->value; // 142

GET systems/<systemKey>/environmental-savings/tree

Returns a list of tree equivalents; that means the amount of trees you would have to plant to absorb the amount of CO2 saved by the given system.

Path parameters

Name	Type	Description
systemKey `required`	`string`	Identification key of the system

Query parameters

Name	Type	Description
from `optional`¹	`date`ǀ`datetime`	Start date
to `optional`¹	`date`ǀ`datetime`	End date
resolution `optional`²	(`day`ǀ`month`ǀ`year`)	Defaults to `day`

Response

Property	Type	Description
timestamp `fixed`	`datetime`	Timestamp
value `fixed`	`integer`ǀ`null`	Number of tree equivalents

Satellite

Irradiance

Get the satellite irradiance data. The data is not the raw satellite irradiance on the horizontal plane but the plane of array irradiance for the whole system, weighted by the installed power of each array.

Request

curl 'https://api.meteocontrol.de/v2/systems/ABCDE/satellite/irradiance?from=2020-09-01T06:00:00+02:00&to=2020-09-01T08:59:59+02:00&resolution=hour'

<?php
    $criteria = (new MeasurementsCriteria())
        ->withDateFrom(DateTime::createFromFormat(DATE_ATOM, '2020-09-01T06:00:00+02:00'))
        ->withDateTo(DateTime::createFromFormat(DATE_ATOM, '2020-09-01T08:59:59+02:00'))
        ->withResolution('hour');
    /** @var MeasurementValue[] $irradianceData */
    $irradianceData = $api->system('ABCDE')->satellite()->irradiance()->get($criteria);

Response

{
  "data": [
    {
      "timestamp": "2020-09-01T07:00:00+02:00",
      "value": 0
    },
    {
      "timestamp": "2020-09-01T08:00:00+02:00",
      "value": 12.3265024145379
    },
    {
      "timestamp": "2020-09-01T09:00:00+02:00",
      "value": 54.2568234978603
    }
  ]
}

<?php
    /** @var MeasurementValue[] $irradianceData */
    echo $irradianceData[0]->timestamp->format(DATE_ATOM);// 2020-09-01T07:00:00+02:00
    echo $irradianceData[0]->value;// 0
    echo $irradianceData[1]->timestamp->format(DATE_ATOM);// 2020-09-01T08:00:00+02:00
    echo $irradianceData[1]->value;// 12.3265024145379

GET systems/<systemKey>/satellite/irradiance

Path parameters

Name	Type	Description
systemKey `required`	`string`	Identification key of the system

Query parameters

Name	Type	Description
from `required`¹	`date`ǀ`datetime`	Start date
to `required`¹	`date`ǀ`datetime`	End date
resolution `optional`	(`interval`ǀ`hour`ǀ`day`ǀ`month`ǀ`year`)	Defaults to `hour`

¹ The maximum time span between from and to varies depending on the resolution as listed below.

Resolution	Maximum time span
interval	31 days
hour	31 days
day	60 days
month	1 year
year	no limitation

Response

Measurement object

Property	Type	Description
timestamp `fixed`	`datetime`	Timestamp
value `fixed`	`number`	Value

Forecasts

Yield

Request

curl 'https://api.meteocontrol.de/v2/systems/ABCDE/forecasts/yield/specific-energy?from=2016-10-01T00:00:00+02:00&to=2016-12-31T23:59:59+01:00'

<?php
    $measurementsCriteria = (new MeasurementsCriteria())
        ->withDateFrom(DateTime::createFromFormat(DATE_ATOM, '2016-10-01T00:00:00+02:00'))
        ->withDateTo(DateTime::createFromFormat(DATE_ATOM, '2016-12-31T23:59:59+01:00'));
    /** @var TimestampValue[] $yields */
    $yields = $api->system('ABCDE')->forecasts()->forecastsYield()->specificEnergy()->get($measurementsCriteria);

Response

{
  "data": [
    {
      "timestamp": "2016-10-01T00:00:00+02:00",
      "value": 59.759999999999998
    },
    {
      "timestamp": "2016-11-01T00:00:00+01:00",
      "value": 33.709620000000001
    },
    {
      "timestamp": "2016-12-01T00:00:00+01:00",
      "value": 24.437856
    }
  ]
}

<?php
    /** @var TimestampValue[] $yields */
    echo $yields[0]->timestamp->format(DATE_ATOM);  // '2016-10-01T00:00:00+02:00'
    echo $yields[0]->value;                         // 59.759999999999998
    echo $yields[1]->timestamp->format(DATE_ATOM);  // '2016-11-01T00:00:00+01:00'
    echo $yields[1]->value;                         // 33.709620000000001
    echo $yields[2]->timestamp->format(DATE_ATOM);  // '2016-12-01T00:00:00+01:00'
    echo $yields[2]->value;                         // 24.437856

GET systems/<systemKey>/forecasts/yield/specific-energy

Returns a list of yield projection values.

Path parameters

Name	Type	Description
systemKey `required`	`string`	Identification key of the system

Query parameters

Name	Type	Description
from `required`¹	`date`ǀ`datetime`	Start date
to `required`¹	`date`ǀ`datetime`	End date

¹ The resolution fixed to month at current moment.

Forecast

Request

curl 'https://api.meteocontrol.de/v2/systems/ABCDE/forecasts/forecast?format=json&hours_into_future=1&timezone=UTC&resolution=fifteen-minutes&category=intraday

<?php
    $forecastCriteria = (new ForecastCriteria())
            ->withFormat('json')
            ->withHoursToFuture(1)
            ->withTimezone('UTC')
            ->withResolution(ForecastCriteria::RESOLUTION_FIFTEEN_MINUTES)
            ->withCategory(ForecastCriteria::CATEGORY_INTRADAY);
    /** @var MeasurementsBulkReader $forecastData */
    $forecastData = $api->system('ABCDE')->forecasts()->forecast()->get($forecastCriteria);

Response

{
    "data": [
        {
            "systemKey": "ABCDE",
            "timestamp": "2021-11-06T12:30:00+00:00",
            "calculation_timestamp": "2021-11-06T10:00:00+00:00",
            "power": 35.31
        },
        {
            "systemKey": "ABCDE",
            "timestamp": "2021-11-06T12:45:00+00:00",
            "calculation_timestamp": "2021-11-06T10:00:00+00:00",
            "power": 40.31
        },
        {
            "systemKey": "ABCDE",
            "timestamp": "2021-11-06T13:00:00+00:00",
            "calculation_timestamp": "2021-11-06T10:00:00+00:00",
            "power": 50.0
        },
        {
            "systemKey": "ABCDE",
            "timestamp": "2021-11-06T13:15:00+00:00",
            "calculation_timestamp": "2021-11-06T10:00:00+00:00",
            "power": 0
        }
    ]
}

<?php
    /** @var MeasurementsBulkReader $forecastData */
    $forecasts = $forecastData->getAsArray();
    echo $forecasts['data'][0]['timestamp'];  // '2021-11-06T12:30:00+00:00'
    echo $forecasts['data'][0]['calculation_timestamp']; // '2021-11-06T10:00:00+00:00'
    echo $forecasts['data'][0]['systemKey']; // 'ABCDE'
    echo $forecasts['data'][0]['power']; // 35.31
    echo $forecasts['data'][1]['timestamp'];  // '2021-11-06T12:45:00+00:00'
    echo $forecasts['data'][1]['calculation_timestamp']; // '2021-11-06T10:00:00+00:00'
    echo $forecasts['data'][1]['systemKey']; // 'ABCDE'
    echo $forecasts['data'][1]['power']; // 40.31
    echo $forecasts['data'][2]['timestamp'];  // '2021-11-06T13:00:00+00:00'
    echo $forecasts['data'][2]['calculation_timestamp']; // 2021-11-06T10:00:00+00:00
    echo $forecasts['data'][2]['systemKey']; // 'ABCDE'
    echo $forecasts['data'][2]['power']; // 50.0
    echo $forecasts['data'][3]['timestamp'];  // '2021-11-06T13:15:00+00:00'
    echo $forecasts['data'][3]['calculation_timestamp']; // '2021-11-06T10:00:00+00:00'
    echo $forecasts['data'][3]['systemKey']; // 'ABCDE'
    echo $forecasts['data'][3]['power']; // 0

GET systems/<systemKey>/forecasts/forecast

Path parameters

Name	Type	Description
systemKey `required`	`string`	Identification key of the system

Query parameters

Name	Type	Description
hours_into_future `optional`	`integer` between 1 and 96	Defaults to `48`
format `optional`	(`json`ǀ`csv`)	Defaults to `json`
resolution `optional`	(`fifteen-minutes`ǀ`thirty-minutes`ǀ`hour`)	Defaults to `fifteen-minutes`
timezone `optional`	`string`	Defaults to `system timezone`
category `optional`	(`dayAhead`ǀ`intraday`ǀ`intradayOptimized`)	Defaults to `contract category`¹

¹ If given a value, the category should be equal to or lower than the contract category. Or the endpoint will respond to HTTP 403.

Response

Property	Type	Description
systemKey `fixed`	`string`	Identification key of the system
timestamp `fixed`	`string`	Timestamp
calculation_timestamp `fixed`	`string`	Calculation timestamp
power `fixed`	`number`	Power value

Forecast contract category

Depending on your contract type different kinds of forecasts are provided.

Category	Description
Day-Ahead	Only day-ahead forecasts can be retrieved. The first timestamp starts at 00:00:00 of the following day. They are based on numerical weather prediction and will update a couple times per day.
Intraday	Both day-ahead and intraday forecasts can be retrieved. They are also based on numerical weather prediction and will update a couple times per day.
Intraday Optimized	Both day-ahead and intraday forecasts can be retrieved. Satellite based forecasts are combined with numerical weather prediction. The forecasts are updated every 15 minutes.

You can contact our sales department at sales@meteocontrol.com to get the contract type of your systems.

Inverters

Get all inverters

Request

curl 'https://api.meteocontrol.de/v2/systems/ABCDE/inverters'

<?php
    /** @var Inverter[] $inverters */
    $inverters = $api->system('ABCDE')->inverters()->get();

Response

{
  "data": [
    {
      "id": "Id12345.1",
      "name": "Inverter 1",
      "serial": "123456788"
    },
    {
      "id": "Id12345.2",
      "name": "Inverter 2",
      "serial": "123456789"
    }
  ]
}

<?php
    /** @var Inverter[] $inverters */
    echo $inverters[0]->id;// Id12345.1
    echo $inverters[0]->name;// Inverter 1
    echo $inverters[0]->serial;// 123456788
    echo $inverters[1]->id;// Id12345.2
    echo $inverters[1]->name;// Inverter 2
    echo $inverters[1]->serial;// 123456789

GET systems/<systemKey>/inverters

Path parameters

Name	Type	Description
systemKey `required`	`string`	Identification key of the system

Response

Property	Type	Description
id `fixed`	`string`	Inverter device ID
name `fixed`	`string`	Custom name
serial `fixed`	`string`ǀ`null`	Serial number if given

Get single inverter

Request

curl 'https://api.meteocontrol.de/v2/systems/ABCDE/inverters/Id12345.1'

<?php
    /** @var InverterDetail $inverter */
    $inverter = $api->system('ABCDE')->inverter('Id12345.1')->get();

Response

{
  "data": {
    "id" : "Id12345.1",
    "model": "TLX 15 k",
    "vendor": "Danfoss",
    "serial": "123456788",
    "name": "Inverter 1",
    "scaleFactor": 24.01,
    "firmware": "1.0"
  }
}

<?php
    /** @var InverterDetail $inverter */
    echo $inverter->id;// Id12345.1
    echo $inverter->model;// TLX 15 k
    echo $inverter->vendor;// Danfoss
    echo $inverter->serial;// 123456788
    echo $inverter->name;// Inverter 1
    echo $inverter->scaleFactor;// 24.01
    echo $inverter->firmware;// 1.0

GET systems/<systemKey>/inverters/<deviceId>

Path parameters

Name	Type	Description
systemKey `required`	`string`	Identification key of the system
deviceId `required`	`string`	Inverter device ID

Response

Property	Type	Description
id `fixed`	`string`	Inverter device ID
model `fixed`	`string`	Model name
vendor `fixed`	`string`	Vendor name
serial `fixed`	`string`ǀ`null`	Serial number if given
name `fixed`	`string`ǀ`null`	Custom name
scaleFactor `fixed`	`number`ǀ`null`	Normalization factor
firmware `fixed`	`string`ǀ`null`	Firmware

Abbreviations

Request

curl 'https://api.meteocontrol.de/v2/systems/ABCDE/inverters/Id12345.1/abbreviations'

<?php
    /** @var string[] $abbreviations */
    $abbreviations = $api->system('ABCDE')->inverter('Id12345.1')->abbreviations()->get();

Response

{
  "data": [
    "P_AC",
    "E_TOTAL",
    "E_INT"
  ]
}

<?php
    /** @var string[] $abbreviations */
    echo $abbreviations[0];// P_AC
    echo $abbreviations[1];// E_TOTAL
    echo $abbreviations[2];// E_INT

GET systems/<systemKey>/inverters/<deviceId>/abbreviations

Returns a list of abbreviation IDs. Common abbreviations within the inverters endpoint are P_AC (AC Power), E_TOTAL (total energy produced) or E_INT (energy produced per interval).

Path parameters

Name	Type	Description
systemKey `required`	`string`	Identification key of the system
deviceId `required`	`string`	Inverter device ID

Get single abbreviation

Request

curl 'https://api.meteocontrol.de/v2/systems/ABCDE/inverters/Id12345.1/abbreviations/P_AC'

<?php
    /** @var Abbreviation $abbreviation */
    $abbreviation = $api->system('ABCDE')->inverter('Id12345.1')->abbreviation('P_AC')->get();

Response

{
  "data": {
    "aggregation": "AVG",
    "precision": 2,
    "description": "Power AC",
    "unit": "W"
  }
}

<?php
    /** @var Abbreviation $abbreviation */
    echo $abbreviation->aggregation;// AVG
    echo $abbreviation->precision;// 2
    echo $abbreviation->description;// Power Ac
    echo $abbreviation->unit;// W

GET systems/<systemKey>/inverters/<deviceId>/abbreviations/<abbreviationId>

Returns an information object of an abbreviation.

Path parameters

Name	Type	Description
systemKey `required`	`string`	Identification key of the system
deviceId `required`	`string`	Inverter device ID
abbreviationId `required`	`string`	Abbreviation ID

Response

Information object

Property	Type	Description
aggregation `fixed`	(`SUM`ǀ`AVG`ǀ`MAX`)	Aggregation method when requesting other resolutions than interval
precision `fixed`	`integer`	Number of decimal places
description `fixed`	`string`	Description
unit `fixed`	`string`	Unit

Measurements

Request

curl 'https://api.meteocontrol.de/v2/systems/ABCDE/inverters/Id12345.1/abbreviations/P_AC/measurements?from=2016-10-21T11:00:00+02:00&to=2016-10-21T12:00:00+02:00'

<?php
    $measurementsCriteria = (new MeasurementsCriteria())
        ->withDateFrom(DateTime::createFromFormat(DATE_ATOM, '2016-10-21T11:00:00+02:00'))
        ->withDateTo(DateTime::createFromFormat(DATE_ATOM, '2016-10-21T12:00:00+02:00'));
    /** @var DevicesMeasurement $measurements */
    $measurements = $api->system('ABCDE')->inverter('Id12345.1')->abbreviation('P_AC')->measurements()
        ->get($measurementsCriteria);

Response

{
  "data": {
    "Id12345.1": {
      "P_AC": [
        {
          "timestamp": "2016-10-21T11:00:00+02:00",
          "value": 0.089
        },
        {
          "timestamp": "2016-10-21T11:15:00+02:00",
          "value": 0.082
        },
        {
          "timestamp": "2016-10-21T11:30:00+02:00",
          "value": 0.078
        },
        {
          "timestamp": "2016-10-21T11:45:00+02:00",
          "value": 0.089
        },
        {
          "timestamp": "2016-10-21T12:00:00+02:00",
          "value": 0.095
        }
      ]
    }
  }
}

<?php
    /** @var DevicesMeasurement $measurements */
    echo $measurements['Id12345.1']['P_AC'][0]
        ->timestamp->format(DATE_ATOM);// 2016-10-21T11:00:00+02:00
    echo $measurements['Id12345.1']['P_AC'][0]->value;// 0.089
    echo $measurements['Id12345.1']['P_AC'][1]
        ->timestamp->format(DATE_ATOM);// 2016-10-21T11:15:00+02:00
    echo $measurements['Id12345.1']['P_AC'][1]->value;// 0.082
    echo $measurements['Id12345.1']['P_AC'][2]
        ->timestamp->format(DATE_ATOM);// 2016-10-21T11:30:00+02:00
    echo $measurements['Id12345.1']['P_AC'][2]->value;// 0.078
    echo $measurements['Id12345.1']['P_AC'][3]
        ->timestamp->format(DATE_ATOM);// 2016-10-21T11:45:00+02:00
    echo $measurements['Id12345.1']['P_AC'][3]->value;// 0.089
    echo $measurements['Id12345.1']['P_AC'][4]
        ->timestamp->format(DATE_ATOM);// 2016-10-21T12:00:00+02:00
    echo $measurements['Id12345.1']['P_AC'][4]->value;// 0.095

GET systems/<systemKey>/inverters/<deviceId>/abbreviations/<abbreviationId>/measurements

Path parameters

Name	Type	Description
systemKey `required`	`string`	Identification key of the system
deviceId `required`	`string`	Can contain up to 10 comma delimited inverter device IDs
abbreviationId `required`	`string`	Can contain up to 5 comma delimited abbreviation IDs

Query parameters

Name	Type	Description
from `required`¹	`date`ǀ`datetime`	Start date
to `required`¹	`date`ǀ`datetime`	End date
resolution `optional`	(`minute²`ǀ`interval`ǀ`fifteen-minutes`ǀ`thirty-minutes`ǀ`hour`ǀ`day`ǀ`month`ǀ`year`)	Defaults to `interval`
includeInterval `optional`³	`integer` `0`ǀ`1`	Defaults to `0`

¹ The maximum time span between from and to varies depending on the resolution as listed below.

Resolution	Maximum time span
minute	1 day
interval	31 days
fifteen-minutes	31 days
thirty-minutes	31 days
hour	31 days
day	60 days
month	1 year
year	no limitation

² The option minute resolution is only supported by meteocontrol blue'Log XM / XC (Firmware 2.0 and higher)
³ Only for interval resolution

Response

Property	Type	Description
timestamp `fixed`	`datetime`	Timestamp
value `fixed`	`number`	Value

Bulk

Request

curl 'https://api.meteocontrol.de/v2/systems/ABCDE/inverters/bulk/measurements?from=2016-10-21T10:00:00+02:00&to=2016-10-21T10:05:00+02:00'

<?php
    $measurementsCriteria = (new MeasurementsCriteria())
        ->withDateFrom(DateTime::createFromFormat(DATE_ATOM, '2016-10-21T10:00:00+02:00'))
        ->withDateTo(DateTime::createFromFormat(DATE_ATOM, '2016-10-21T10:05:00+02:00'));
    $bulkData = $api->system('ABCDE')->inverters()->bulk()->measurements()
        ->get($measurementsCriteria);

Response

{
  "2016-10-21T10:00:00+02:00": {
    "Id12345.1": {
      "COS_PHI": 0,
      "E_DAY": 0,
      "E_INT": 0.038,
      "E_INT_N": 0.04,
      "E_TOTAL": 3606.5,
      "F_AC": 59.988799999999998,
      "I_AC": 0,
      "I_AC1": 0,
      "I_AC2": 0,
      "I_AC3": 0,
      "I_DC": 0,
      "P_AC": 454.34,
      "P_AC_N": 0,
      "P_DC": 0,
      "U_AC_L1L2": 386.67500000000001,
      "U_AC_L2L3": 386.83800000000002,
      "U_AC_L3L1": 384.67599999999999,
      "U_DC": 0
    },
    "Id12345.2": {
      "COS_PHI": 0,
      "E_DAY": 0,
      "E_INT": 0.038,
      "E_INT_N": 0.04,
      "E_TOTAL": 3212.1999999999998,
      "F_AC": 59.986800000000002,
      "I_AC": 0,
      "I_AC1": 0,
      "I_AC2": 0,
      "I_AC3": 0,
      "I_DC": 0,
      "P_AC": 452.34,
      "P_AC_N": 0,
      "P_DC": 0,
      "U_AC_L1L2": 386.63999999999999,
      "U_AC_L2L3": 387.07299999999998,
      "U_AC_L3L1": 384.56400000000002,
      "U_DC": 0
    }
  },
  "2016-10-21T10:05:00+02:00": {
    "Id12345.1": {
      "COS_PHI": 0,
      "E_DAY": 0,
      "E_INT": 0.044,
      "E_INT_N": 0.04,
      "E_TOTAL": 3606.5,
      "F_AC": 60,
      "I_AC": 0,
      "I_AC1": 0,
      "I_AC2": 0,
      "I_AC3": 0,
      "I_DC": 0,
      "P_AC": 529.38,
      "P_AC_N": 0,
      "P_DC": 0,
      "U_AC_L1L2": 386.66300000000001,
      "U_AC_L2L3": 386.88299999999998,
      "U_AC_L3L1": 384.53500000000003,
      "U_DC": 0
    },
    "Id12345.2": {
      "COS_PHI": 0,
      "E_DAY": 0,
      "E_INT": 0.043,
      "E_INT_N": 0.04,
      "E_TOTAL": 3212.1999999999998,
      "F_AC": 60,
      "I_AC": 0,
      "I_AC1": 0,
      "I_AC2": 0,
      "I_AC3": 0,
      "I_DC": 0,
      "P_AC": 519.09,
      "P_AC_N": 0,
      "P_DC": 0,
      "U_AC_L1L2": 386.47000000000003,
      "U_AC_L2L3": 387.024,
      "U_AC_L3L1": 384.673,
      "U_DC": 0
    }
  }
}

<?php
    /** @var MeasurementsBulkReader $bulkData */
    $bulkDataArray = $bulkData->getAsArray();
    echo $bulkDataArray['2016-10-21T10:00:00+02:00']['Id12345.1']['P_AC'];// 454.34
    echo $bulkDataArray['2016-10-21T10:00:00+02:00']['Id12345.1']['E_INT'];// 0.038
    echo $bulkDataArray['2016-10-21T10:00:00+02:00']['Id12345.1']['E_INT_N'];// 0.04
    echo $bulkDataArray['2016-10-21T10:00:00+02:00']['Id12345.2']['P_AC'];// 452.34
    echo $bulkDataArray['2016-10-21T10:00:00+02:00']['Id12345.2']['E_INT'];// 0.038
    echo $bulkDataArray['2016-10-21T10:00:00+02:00']['Id12345.2']['E_INT_N'];// 0.04
    echo $bulkDataArray['2016-10-21T10:05:00+02:00']['Id12345.1']['P_AC'];// 529.38
    echo $bulkDataArray['2016-10-21T10:05:00+02:00']['Id12345.1']['E_INT'];// 0.044
    echo $bulkDataArray['2016-10-21T10:05:00+02:00']['Id12345.1']['E_INT_N'];// 0.04
    echo $bulkDataArray['2016-10-21T10:05:00+02:00']['Id12345.2']['P_AC'];// 519.09
    echo $bulkDataArray['2016-10-21T10:05:00+02:00']['Id12345.2']['E_INT'];// 0.043
    echo $bulkDataArray['2016-10-21T10:05:00+02:00']['Id12345.2']['E_INT_N'];// 0.04

GET systems/<systemKey>/inverters/bulk/measurements

Path parameters

Name	Type	Description
systemKey `required`	`string`	Identification key of the system

Query parameters

Name	Type	Description
from `required`¹	`date`ǀ`datetime`	Start date
to `required`¹	`date`ǀ`datetime`	End date
format `optional`	`json`ǀ`csv`	Export format, defaults to `json`
resolution `optional`	(`minute²`ǀ`interval`ǀ`fifteen-minutes`ǀ`thirty-minutes`ǀ`hour`ǀ`day`)	Defaults to `interval`
deviceIds `optional`	`string`	Comma separated deviceIds
abbreviations `optional`	`string`	Comma separated abbreviations
includeInterval `optional`³	`integer` `0`ǀ`1`	Defaults to `0`

Options for CSV format

The following query parameters are valid only if format is csv
For response example in CSV format, please check HERE.

Name	Type	Description
delimiter	`comma`ǀ`semicolon`ǀ`colon`ǀ`tab`	The delimiter, defaults to `comma`
lineBreak	`LF`ǀ`CR`ǀ`CR/LF`	The line breaks, defaults to `LF`
decimalPoint	`dot`ǀ`comma`	The decimal point, defaults to `dot`
emptyPlaceholder	`text`, empty string by default, any text accepted	The place holder for empty value
precision	`integer`, accepts from 0 to 4	The decimal precision, defaults to `2`

PR

Request

curl 'https://api.meteocontrol.de/v2/systems/ABCDE/inverters/pr?from=2016-10-23&to=2016-10-25&resolution=day&deviceIds=Id12345.1,Id12345.2,Id12345.3'

<?php
    $criteria = (new InverterPrCriteria())
        ->withDateFrom(DateTime::createFromFormat('Y-m-d', '2016-10-23'))
        ->withDateTo(DateTime::createFromFormat('Y-m-d', '2016-10-25'))
        ->withResolution(MeasurementsCriteria::RESOLUTION_DAY)
        ->withDeviceIds(['Id12345.1', 'Id12345.2', 'Id12345.3']);
    $prData = $api->system('ABCDE')->inverters()->pr()->get($criteria);

Response

{
  "data": {
    "2016-10-23T00:00:00+02:00": {
      "Id12345.1": 78.67,
      "Id12345.2": 82.05,
      "Id12345.3": 0
    },
    "2016-10-24T00:00:00+02:00": {
      "Id12345.1": 80.24,
      "Id12345.2": 85.12,
      "Id12345.3": 0
    },
    "2016-10-25T00:00:00+02:00": {
      "Id12345.1": 79.05,
      "Id12345.2": 83.18,
      "Id12345.3": 0
    }
  }
}

<?php
    /** @var array $prData */
    echo $prData['2016-10-23T00:00:00+02:00']['Id12345.1'];// 78.67
    echo $prData['2016-10-23T00:00:00+02:00']['Id12345.2'];// 82.05
    echo $prData['2016-10-23T00:00:00+02:00']['Id12345.3'];// 0

GET systems/<systemKey>/inverters/pr

Path parameters

Name	Type	Description
systemKey `required`	`string`	Identification key of the system

Query parameters

Name	Type	Description
from `required`¹	`date`	Start date
to `required`¹	`date`	End date
deviceIds `required`	`string`	Comma separated deviceIds²
resolution `optional`¹	(`day`ǀ`month`)	Defaults to `day`

¹ The maximum time span between from and to varies depending on the resolution as listed below.
² The maximum number of deviceIds is 10.

Resolution	Maximum time span
day	60 days
month	1 year

Meters

Get all meters

Request

curl 'https://api.meteocontrol.de/v2/systems/ABCDE/meters'

<?php
    /** @var Meter[] $meters */
    $meters = $api->system('ABCDE')->meters()->get();

Response

{
  "data": [
    {
      "id": "12345",
      "name": "Meter 1",
      "uid": "1"
    },
    {
      "id": "12346",
      "name": "Meter 2",
      "uid": "2"
    }
  ]
}

<?php
    /** @var Meter[] $meters */
    echo $meters[0]->id;// 12345
    echo $meters[0]->name;// Meter 1
    echo $meters[0]->uid;// 1
    echo $meters[1]->id;// 12346
    echo $meters[1]->name;// Meter 2
    echo $meters[1]->uid;// 2

GET systems/<systemKey>/meters

Path parameters

Name	Type	Description
systemKey `required`	`string`	Identification key of the system

Response

Property	Type	Description
id `fixed`	`string`	Meter device ID
name `fixed`	`string`	Custom name
uid `fixed`	`string`ǀ`null`	UID

Get single meter

Request

curl 'https://api.meteocontrol.de/v2/systems/ABCDE/meters/12345'

<?php
    /** @var MeterDetail $meter */
    $meter = $api->system('ABCDE')->meter('12345')->get();

Response

{
  "data": {
    "id": "12345",
    "name": "Meter 1",
    "uid": "1",
    "address": "1",
    "firmware": "1.0"
  }
}

<?php
    /** @var MeterDetail $meter */
    echo $meter->id;// 12345
    echo $meter->name;// Meter 1
    echo $meter->uid;// 1
    echo $meter->address;// 1
    echo $meter->firmware;// 1.0

GET systems/<systemKey>/meters/<deviceId>

Path parameters

Name	Type	Description
systemKey `required`	`string`	Identification key of the system
deviceId `required`	`string`	Meter device ID

Response

Property	Type	Description
id `fixed`	`string`	Meter device ID
name `fixed`	`string`	Custom name
uid `fixed`	`string`ǀ`null`	UID
address `fixed`	`string`ǀ`null`	Address
firmware `fixed`	`string`ǀ`null`	Firmware

Abbreviations

Request

curl 'https://api.meteocontrol.de/v2/systems/ABCDE/meters/12345/abbreviations'

<?php
    /** @var string[] $abbreviations */
    $abbreviations = $api->system('ABCDE')->meter('12345')->abbreviations()->get();

Response

{
  "data": [
    "M_AC_E_EXP",
    "M_E_INT_EXP",
    "M_AC_E_IMP",
    "M_E_INT_IMP"
  ]
}

<?php
    /** @var string[] $abbreviations */
    echo $abbreviations[0];// M_AC_E_EXP
    echo $abbreviations[1];// M_E_INT_EXP
    echo $abbreviations[2];// M_AC_E_IMP
    echo $abbreviations[3];// M_E_INT_IMP

GET systems/<systemKey>/meters/<deviceId>/abbreviations

Path parameters

Name	Type	Description
systemKey `required`	`string`	Identification key of the system
deviceId `required`	`string`	Meter device ID

Get single abbreviation

Request

curl 'https://api.meteocontrol.de/v2/systems/ABCDE/meters/12345/abbreviations/M_AC_E_EXP'

<?php
    /** @var Abbreviation $abbreviation */
    $abbreviation = $api->system('ABCDE')->meter('12345')->abbreviation('M_AC_E_EXP')->get();

Response

{
  "data": {
    "aggregation": "MAX",
    "precision": 3,
    "description": "Active energy (export)",
    "unit": "kWh"
  }
}

<?php
    /** @var Abbreviation $abbreviation */
    echo $abbreviation->aggregation;// MAX
    echo $abbreviation->precision;// 3
    echo $abbreviation->description;// Active energy (export)
    echo $abbreviation->unit;// kWh

GET systems/<systemKey>/meters/<deviceId>/abbreviations/<abbreviationId>

Returns an information object of an abbreviation.

Path parameters

Name	Type	Description
systemKey `required`	`string`	Identification key of the system
deviceId `required`	`string`	Meter device ID
abbreviationId `required`	`string`	Abbreviation ID

Response

Information object

Property	Type	Description
aggregation `fixed`	(`SUM`ǀ`AVG`ǀ`MAX`)	Aggregation method when requesting other resolutions than interval
precision `fixed`	`integer`	Number of decimal places
description `fixed`	`string`	Description
unit `fixed`	`string`	Unit

Measurements

Request

curl 'https://api.meteocontrol.de/v2/systems/ABCDE/meters/12345/abbreviations/E/measurements?from=2016-11-01T11:00:00+02:00&to=2016-11-01T11:15:00+02:00'

<?php
    $measurementsCriteria = (new MeasurementsCriteria())
        ->withDateFrom(DateTime::createFromFormat(DATE_ATOM, '2016-11-01T11:00:00+02:00'))
        ->withDateTo(DateTime::createFromFormat(DATE_ATOM, '2016-11-01T11:15:00+02:00'));
    /** @var DevicesMeasurement $measurements */
    $measurements = $api->system('ABCDE')->meter('12345')->abbreviation('E')->measurements()
        ->get($measurementsCriteria);

Response

{
  "data": {
    "12345": {
      "E": [
        {
          "timestamp": "2016-11-01T11:00:00+02:00",
          "value": 7119.21
        },
        {
          "timestamp": "2016-11-01T11:15:00+02:00",
          "value": 7119.21
        }
      ]
    }
  }
}

<?php
    /** @var DevicesMeasurement $measurements */
    echo $measurements['12345']['E'][0]
        ->timestamp->format(DATE_ATOM);// 2016-11-01T11:00:00+02:00
    echo $measurements['12345']['E'][0]->value;// 7119.21
    echo $measurements['12345']['E'][1]
        ->timestamp->format(DATE_ATOM);// 2016-11-01T11:15:00+02:00
    echo $measurements['12345']['E'][1]->value;// 7119.21

GET systems/<systemKey>/meters/<deviceId>/abbreviations/<abbreviationId>/measurements

Path parameters

Name	Type	Description
systemKey `required`	`string`	Identification key of the system
deviceId `required`	`string`	Can contain up to 10 comma delimited meter device IDs
abbreviationId `required`	`string`	Can contain up to 5 comma delimited abbreviation IDs

Query parameters

Name	Type	Description
from `required`¹	`date`ǀ`datetime`	Start date
to `required`¹	`date`ǀ`datetime`	End date
resolution `optional`	(`minute²`ǀ`interval`ǀ`fifteen-minutes`ǀ`thirty-minutes`ǀ`hour`ǀ`day`ǀ`month`ǀ`year`)	Defaults to `interval`
includeInterval `optional`³	`integer` `0`ǀ`1`	Defaults to `0`

¹ The maximum time span between from and to varies depending on the resolution as listed below.

Resolution	Maximum time span
minute	1 day
interval	31 days
fifteen-minutes	31 days
thirty-minutes	31 days
hour	31 days
day	60 days
month	1 year
year	no limitation

² The option minute resolution is only supported by meteocontrol blue'Log XM / XC (Firmware 2.0 and higher)
³ Only for interval resolution

Response

Property	Type	Description
timestamp `fixed`	`datetime`	Timestamp
value `fixed`	`number`	Value

Bulk

Request

curl 'https://api.meteocontrol.de/v2/systems/ABCDE/meters/bulk/measurements?from=2016-11-01T10:00:00+02:00&to=2016-11-01T10:05:00+02:00'

<?php
    $measurementsCriteria = (new MeasurementsCriteria())
        ->withDateFrom(DateTime::createFromFormat(DATE_ATOM, '2016-11-01T10:00:00+02:00'))
        ->withDateTo(DateTime::createFromFormat(DATE_ATOM, '2016-11-01T10:05:00+02:00'));
    $bulkData = $api->system('ABCDE')->meters()->bulk()->measurements()
        ->get($measurementsCriteria);

Response

{
  "2016-11-01T10:00:00+02:00": {
    "12345": {
      "E": 7127.4,
      "E_TOTAL": 1304876,
      "P": null,
      "E_INT": 0
    },
    "12346": {
      "E": 872.6,
      "E_TOTAL": 2239659.75,
      "P": null,
      "E_INT": 0
    }
  },
  "2016-11-01T10:05:00+02:00": {
    "12345": {
      "E": 7127.49,
      "E_TOTAL": 1304876,
      "P": null,
      "E_INT": 0
    },
    "12346": {
      "E": 872.6,
      "E_TOTAL": 2239669.25,
      "P": null,
      "E_INT": 0
    }
  }
}

<?php
    /** @var array $bulkDataArray */
    $bulkDataArray = $bulkData->getAsArray();
    echo $bulkDataArray['2016-11-01T10:00:00+02:00']['12345']['E'];// 7127.4
    echo $bulkDataArray['2016-11-01T10:00:00+02:00']['12345']['E_TOTAL'];// 1304876
    echo $bulkDataArray['2016-11-01T10:00:00+02:00']['12346']['E'];// 872.6
    echo $bulkDataArray['2016-11-01T10:00:00+02:00']['12346']['E_TOTAL'];// 2239659.75
    echo $bulkDataArray['2016-11-01T10:05:00+02:00']['12345']['E'];// 7127.49
    echo $bulkDataArray['2016-11-01T10:05:00+02:00']['12345']['E_TOTAL'];// 1304876
    echo $bulkDataArray['2016-11-01T10:05:00+02:00']['12346']['E'];// 872.6
    echo $bulkDataArray['2016-11-01T10:05:00+02:00']['12346']['E_TOTAL'];// 2239669.25

GET systems/<systemKey>/meters/bulk/measurements

Path parameters

Name	Type	Description
systemKey `required`	`string`	Identification key of the system

Query parameters

Name	Type	Description
from `required`¹	`date`ǀ`datetime`	Start date
to `required`¹	`date`ǀ`datetime`	End date
format `optional`	`json`ǀ`csv`	Export format, defaults to `json`
resolution `optional`	(`minute²`ǀ`interval`ǀ`fifteen-minutes`ǀ`thirty-minutes`ǀ`hour`ǀ`day`)	Defaults to `interval`
deviceIds `optional`	`string`	Comma separated deviceIds
abbreviations `optional`	`string`	Comma separated abbreviations
includeInterval `optional`³	`integer` `0`ǀ`1`	Defaults to `0`

Options for CSV format

The following query parameters are valid only if format is csv
For response example in CSV format, please check HERE.

Name	Type	Description
delimiter	`comma`ǀ`semicolon`ǀ`colon`ǀ`tab`	The delimiter, defaults to `comma`
lineBreak	`LF`ǀ`CR`ǀ`CR/LF`	The line breaks, defaults to `LF`
decimalPoint	`dot`ǀ`comma`	The decimal point, defaults to `dot`
emptyPlaceholder	`text`, empty string by default, any text accepted	The place holder for empty value
precision	`integer`, accepts from 0 to 4	The decimal precision, defaults to `2`

Sensors

Get all sensor devices

Request

curl 'https://api.meteocontrol.de/v2/systems/ABCDE/sensors'

<?php
    /** @var Sensor[] $sensors */
    $sensors = $api->system('ABCDE')->sensors()->get();

Response

{
  "data": [
    {
      "id": "10001",
      "name": "Pyranometer SMPx (Modbus)",
      "uid": "7"
    },
    {
      "id": "10002",
      "name": "Irradiation sensor M&T / mc Si-420TC-T (4 - 20mA)",
      "uid": "8"
    }
  ]
}

<?php
    /** @var Sensor[] $sensors */
    echo $sensors[0]->id;// 10001
    echo $sensors[0]->name;// Pyranometer SMPx (Modbus)
    echo $sensors[0]->uid;// 7
    echo $sensors[1]->id;// 10002
    echo $sensors[1]->name;// Irradiation sensor M&T / mc Si-420TC-T (4 - 20mA)
    echo $sensors[1]->uid;// 8

GET systems/<systemKey>/sensors

Path parameters

Name	Type	Description
systemKey `required`	`string`	Identification key of the system

Response

Property	Type	Description
id `fixed`	`string`	Sensor device ID
name `fixed`	`string`	Custom name
uid `fixed`	`string`ǀ`null`	UID

Get single sensor device

Request

curl 'https://api.meteocontrol.de/v2/systems/ABCDE/sensors/10001'

<?php
    /** @var SensorDetail $sensor */
    $sensor = $api->system('ABCDE')->sensor('10001')->get();

Response

{
  "data": {
    "id": "10001",
    "name": "Pyranometer SMPx (Modbus)",
    "uid": "7",
    "address": "7",
    "firmware": "1.0"
  }
}

<?php
    /** @var SensorDetail $sensor */
    echo $sensor->id;// 10001
    echo $sensor->name;// Pyranometer SMPx (Modbus)
    echo $sensor->uid;// 7
    echo $sensor->address;// 7
    echo $sensor->firmware;// 1.0

GET systems/<systemKey>/sensors/<deviceId>

Path parameters

Name	Type	Description
systemKey `required`	`string`	Identification key of the system
deviceId `required`	`string`	Sensor device ID

Response

Property	Type	Description
id `fixed`	`string`	Sensor device ID
name `fixed`	`string`	Custom name
uid `fixed`	`string`ǀ`null`	UID
address `fixed`	`string`ǀ`null`	Address
firmware `fixed`	`string`ǀ`null`	Firmware

Abbreviations

Request

curl 'https://api.meteocontrol.de/v2/systems/ABCDE/sensors/10001/abbreviations'

<?php
    /** @var string[] $abbreviations */
    $abbreviations = $api->system('ABCDE')->sensor('10001')->abbreviations()->get();

Response

{
  "data": [
    "SRAD"
  ]
}

<?php
    /** @var string[] $abbreviations */
    echo $abbreviations[0];// SRAD

GET systems/<systemKey>/sensors/<deviceId>/abbreviations

Path parameters

Name	Type	Description
systemKey `required`	`string`	Identification key of the system
deviceId `required`	`string`	Sensor device ID

Get single abbreviation

Request

curl 'https://api.meteocontrol.de/v2/systems/ABCDE/sensors/10001/abbreviations/SRAD'

<?php
    /** @var string[] $abbreviation */
    $abbreviation = $api->system('ABCDE')->sensor('10001')->abbreviation('SRAD')->get();

Response

{
  "data": {
    "aggregation": "AVG",
    "precision": 3,
    "description": "Irradiance on module plane",
    "unit": "W/m²"
  }
}

<?php
    /** @var Abbreviation $abbreviation */
    echo $abbreviation->aggregation;// AVG
    echo $abbreviation->precision;// 3
    echo $abbreviation->description;// Irradiance on module plane
    echo $abbreviation->unit;// W/m²

GET systems/<systemKey>/sensors/<deviceId>/abbreviations/<abbreviationId>

Returns an information object of an abbreviation.

Path parameters

Name	Type	Description
systemKey `required`	`string`	Identification key of the system
deviceId `required`	`string`	Sensor device ID
abbreviationId `required`	`string`	Abbreviation ID

Response

Information object

Property	Type	Description
aggregation `fixed`	(`SUM`ǀ`AVG`ǀ`MAX`)	Aggregation method when requesting other resolutions than interval
precision `fixed`	`integer`	Number of decimal places
description `fixed`	`string`	Description
unit `fixed`	`string`	Unit

Measurements

Request

curl 'https://api.meteocontrol.de/v2/systems/ABCDE/sensors/10001/abbreviations/SRAD/measurements?from=2016-10-21T20:00:00+02:00&to=2016-10-21T20:05:00+02:00'

<?php
    $measurementsCriteria = (new MeasurementsCriteria())
        ->withDateFrom(DateTime::createFromFormat(DATE_ATOM, '2016-10-21T20:00:00+02:00'))
        ->withDateTo(DateTime::createFromFormat(DATE_ATOM, '2016-10-21T20:05:00+02:00'));
    /** @var DevicesMeasurement $measurements */
    $measurements = $api->system('ABCDE')->sensor('10001')->abbreviation('SRAD')->measurements()
        ->get($measurementsCriteria);

Response

{
  "data": {
    "10001": {
      "SRAD": [
        {
          "timestamp": "2016-10-21T20:00:00+02:00",
          "value": 177.2
        },
        {
          "timestamp": "2016-10-21T20:05:00+02:00",
          "value": 157.2
        }
      ]
    }
  }
}

<?php
    /** @var DevicesMeasurement $measurements */
    echo $measurements['10001']['SRAD'][0]
        ->timestamp->format(DATE_ATOM);// 2016-10-21T20:00:00+02:00
    echo $measurements['10001']['SRAD'][0]->value;// 177.2
    echo $measurements['10001']['SRAD'][1]
        ->timestamp->format(DATE_ATOM);// 2016-10-21T20:05:00+02:00
    echo $measurements['10001']['SRAD'][1]->value;// 157.2

GET systems/<systemKey>/sensors/<deviceId>/abbreviations/<abbreviationId>/measurements

Path parameters

Name	Type	Description
systemKey `required`	`string`	Identification key of the system
deviceId `required`	`string`	Can contain up to 10 comma delimited sensor device IDs
abbreviationId `required`	`string`	Can contain up to 5 comma delimited abbreviation IDs

Query parameters

Name	Type	Description
from `required`¹	`date`ǀ`datetime`	Start date
to `required`¹	`date`ǀ`datetime`	End date
resolution `optional`	(`minute²`ǀ`interval`ǀ`fifteen-minutes`ǀ`thirty-minutes`ǀ`hour`ǀ`day`ǀ`month`ǀ`year`)	Defaults to `interval`
includeInterval `optional`³	`integer` `0`ǀ`1`	Defaults to `0`

¹ The maximum time span between from and to varies depending on the resolution as listed below.

Resolution	Maximum time span
minute	1 day
interval	31 days
fifteen-minutes	31 days
thirty-minutes	31 days
hour	31 days
day	60 days
month	1 year
year	no limitation

² The option minute resolution is only supported by meteocontrol blue'Log XM / XC (Firmware 2.0 and higher)
³ Only for interval resolution

Response

Property	Type	Description
timestamp `fixed`	`datetime`	Timestamp
value `fixed`	`number`	Value

Bulk

Request

curl 'https://api.meteocontrol.de/v2/systems/ABCDE/sensors/bulk/measurements?from=2016-10-21T20:00:00+02:00&to=2016-10-21T20:05:00+02:00'

<?php
    $measurementsCriteria = (new MeasurementsCriteria())
        ->withDateFrom(DateTime::createFromFormat(DATE_ATOM, '2016-10-21T20:00:00+02:00'))
        ->withDateTo(DateTime::createFromFormat(DATE_ATOM, '2016-10-21T20:05:00+02:00'));
    $bulkData = $api->system('ABCDE')->sensors()->bulk()->measurements()
        ->get($measurementsCriteria);

Response

{
  "2016-10-21T20:00:00+02:00": {
    "10001": {
      "SRAD": 441.7
    },
    "10002": {
      "T": 10000.30,
      "SRAD": 78910,
      "STATE": 55.66
    }
  },
  "2016-10-21T20:05:00+02:00": {
    "10001": {
      "SRAD": 525.5
    },
    "10002": {
      "T": 10080.30,
      "SRAD": 78990,
      "STATE": 77.88
    }
  }
}

<?php
    /** @var MeasurementsBulkReader $bulkData */
    $bulkDataArray = $bulkData->getAsArray();
    echo $bulkDataArray['2016-10-21T20:00:00+02:00']['10001']['SRAD'];// 441.7
    echo $bulkDataArray['2016-10-21T20:00:00+02:00']['10002']['T'];// 10000.30
    echo $bulkDataArray['2016-10-21T20:00:00+02:00']['10002']['SRAD'];// 78910
    echo $bulkDataArray['2016-10-21T20:00:00+02:00']['10002']['STATE'];// 55.66
    echo $bulkDataArray['2016-10-21T20:05:00+02:00']['10001']['SRAD'];// 525.5
    echo $bulkDataArray['2016-10-21T20:05:00+02:00']['10002']['T'];// 10080.30
    echo $bulkDataArray['2016-10-21T20:05:00+02:00']['10002']['SRAD'];// 78990
    echo $bulkDataArray['2016-10-21T20:05:00+02:00']['10002']['STATE'];// 77.88

GET systems/<systemKey>/sensors/bulk/measurements

Path parameters

Name	Type	Description
systemKey `required`	`string`	Identification key of the system

Query parameters

Name	Type	Description
from `required`¹	`date`ǀ`datetime`	Start date
to `required`¹	`date`ǀ`datetime`	End date
format `optional`	`json`ǀ`csv`	Export format, defaults to `json`
resolution `optional`	(`minute²`ǀ`interval`ǀ`fifteen-minutes`ǀ`thirty-minutes`ǀ`hour`ǀ`day`)	Defaults to `interval`
deviceIds `optional`	`string`	Comma separated deviceIds
abbreviations `optional`	`string`	Comma separated abbreviations
includeInterval `optional`³	`integer` `0`ǀ`1`	Defaults to `0`

Options for CSV format

The following query parameters are valid only if format is csv
For response example in CSV format, please check HERE.

Name	Type	Description
delimiter	`comma`ǀ`semicolon`ǀ`colon`ǀ`tab`	The delimiter, defaults to `comma`
lineBreak	`LF`ǀ`CR`ǀ`CR/LF`	The line breaks, defaults to `LF`
decimalPoint	`dot`ǀ`comma`	The decimal point, defaults to `dot`
emptyPlaceholder	`text`, empty string by default, any text accepted	The place holder for empty value
precision	`integer`, accepts from 0 to 4	The decimal precision, defaults to `2`

Status

Get all status devices

Request

curl 'https://api.meteocontrol.de/v2/systems/ABCDE/statuses'

<?php
    /** @var Status[] $statuses */
    $statuses = $api->system('ABCDE')->statuses()->get();

Response

{
  "data": [
    {
      "id": "10001",
      "name": "Meldung LS TST",
      "uid": "BT1980004134-D_IN1"
    },
    {
      "id": "10002",
      "name": "Warnung Trafotemperatur",
      "uid": "BT1980004134-D_IN2"
    }
  ]
}

<?php
    /** @var Status[] $statuses */
    echo $statuses[0]->id;// 10001
    echo $statuses[0]->name;// Meldung LS TST
    echo $statuses[0]->uid;// BT1980004134-D_IN1
    echo $statuses[1]->id;// 10002
    echo $statuses[1]->name;// Warnung Trafotemperatur
    echo $statuses[1]->uid;// BT1980004134-D_IN2

GET systems/<systemKey>/statuses

Path parameters

Name	Type	Description
systemKey `required`	`string`	Identification key of the system

Response

Property	Type	Description
id `fixed`	`string`	Status device ID
name `fixed`	`string`	Custom name
uid `fixed`	`string`ǀ`null`	UID

Get single status device

Request

curl 'https://api.meteocontrol.de/v2/systems/ABCDE/statuses/10001'

<?php
    /** @var StatusDetail $status */
    $status = $api->system('ABCDE')->status('10001')->get();

Response

{
  "data": {
    "id": "10001",
    "name": "Meldung LS TST",
    "uid": "BT1980004134-D_IN1",
    "address": "BT1980004134-D_IN1",
    "vendor": "Huawei",
    "model": "SmartLogger 2000 DI Status",
    "firmware": "V200R002C20SPC119"
  }
}

<?php
    /** @var StatusDetail $status */
    echo $status->id;// 10001
    echo $status->name;// Meldung LS TST
    echo $status->uid;// BT1980004134-D_IN1
    echo $status->address;// BT1980004134-D_IN1
    echo $status->vendor;// Huawei
    echo $status->model;// SmartLogger 2000 DI Status
    echo $status->firmware;// V200R002C20SPC119

GET systems/<systemKey>/statuses/<deviceId>

Path parameters

Name	Type	Description
systemKey `required`	`string`	Identification key of the system
deviceId `required`	`string`	Status device ID

Response

Property	Type	Description
id `fixed`	`string`	Status device ID
name `fixed`	`string`	Custom name
uid `fixed`	`string`ǀ`null`	UID
address `fixed`	`string`ǀ`null`	Address
vendor `fixed`	`string`ǀ`null`	Vendor
model `fixed`	`string`ǀ`null`	Model
firmware `fixed`	`string`ǀ`null`	Firmware

Abbreviations

Request

curl 'https://api.meteocontrol.de/v2/systems/ABCDE/statuses/10001/abbreviations'

<?php
    /** @var string[] $abbreviations */
    $abbreviations = $api->system('ABCDE')->status('10001')->abbreviations()->get();

Response

{
  "data": [
    "STATE"
  ]
}

<?php
    /** @var string[] $abbreviations */
    echo $abbreviations[0];// STATE

GET systems/<systemKey>/statuses/<deviceId>/abbreviations

Path parameters

Name	Type	Description
systemKey `required`	`string`	Identification key of the system
deviceId `required`	`string`	Status device ID

Get single abbreviation

Request

curl 'https://api.meteocontrol.de/v2/systems/ABCDE/statuses/10001/abbreviations/STATE'

<?php
    /** @var string[] $abbreviation */
    $abbreviation = $api->system('ABCDE')->status('10001')->abbreviation('STATE')->get();

Response

{
  "data": {
    "aggregation": "MAX",
    "precision": 0,
    "description": "Status",
    "unit": ""
  }
}

<?php
    /** @var Abbreviation $abbreviation */
    echo $abbreviation->aggregation;// MAX
    echo $abbreviation->precision;// 0
    echo $abbreviation->description;// Status
    echo $abbreviation->unit;//

GET systems/<systemKey>/statuses/<deviceId>/abbreviations/<abbreviationId>

Returns an information object of an abbreviation.

Path parameters

Name	Type	Description
systemKey `required`	`string`	Identification key of the system
deviceId `required`	`string`	Status device ID
abbreviationId `required`	`string`	Abbreviation ID

Response

Information object

Property	Type	Description
aggregation `fixed`	(`SUM`ǀ`AVG`ǀ`MAX`)	Aggregation method when requesting other resolutions than interval
precision `fixed`	`integer`	Number of decimal places
description `fixed`	`string`	Description
unit `fixed`	`string`	Unit

Measurements

Request

curl 'https://api.meteocontrol.de/v2/systems/ABCDE/statuses/10001/abbreviations/STATE/measurements?from=2020-10-01T00:00:00+02:00&to=2020-10-01T00:05:00+02:00'

<?php
    $measurementsCriteria = (new MeasurementsCriteria())
        ->withDateFrom(DateTime::createFromFormat(DATE_ATOM, '2020-10-01T00:00:00+02:00'))
        ->withDateTo(DateTime::createFromFormat(DATE_ATOM, '2020-10-01T00:05:00+02:00'));
    /** @var DevicesMeasurement $measurements */
    $measurements = $api->system('ABCDE')->status('10001')->abbreviation('STATE')->measurements()
        ->get($measurementsCriteria);

Response

{
  "data": {
    "10001": {
      "STATE": [
        {
          "timestamp": "2020-10-01T00:00:00+02:00",
          "value": 0
        },
        {
          "timestamp": "2020-10-01T00:05:00+02:00",
          "value": 1
        }
      ]
    }
  }
}

<?php
    /** @var DevicesMeasurement $measurements */
    echo $measurements['10001']['STATE'][0]
        ->timestamp->format(DATE_ATOM);// 2020-10-01T00:00:00+02:00
    echo $measurements['10001']['STATE'][0]->value;// 0
    echo $measurements['10001']['STATE'][1]
        ->timestamp->format(DATE_ATOM);// 2020-10-01T00:05:00+02:00
    echo $measurements['10001']['STATE'][1]->value;// 1

GET systems/<systemKey>/statuses/<deviceId>/abbreviations/<abbreviationId>/measurements

Path parameters

Name	Type	Description
systemKey `required`	`string`	Identification key of the system
deviceId `required`	`string`	Can contain up to 10 comma delimited status device IDs
abbreviationId `required`	`string`	Can contain up to 5 comma delimited abbreviation IDs

Query parameters

Name	Type	Description
from `required`¹	`date`ǀ`datetime`	Start date
to `required`¹	`date`ǀ`datetime`	End date
includeInterval `optional`	`integer` `0`ǀ`1`	Defaults to `0`

¹ The maximum time span is 24 hours between from and to.

Response

Property	Type	Description
timestamp `fixed`	`datetime`	Timestamp
value `fixed`	`number`	Value

Bulk

Request

curl 'https://api.meteocontrol.de/v2/systems/ABCDE/statuses/bulk/measurements?from=2020-10-01T00:00:00+02:00&to=2020-10-01T00:05:00+02:00'

<?php
    $measurementsCriteria = (new MeasurementsCriteria())
        ->withDateFrom(DateTime::createFromFormat(DATE_ATOM, '2020-10-01T00:00:00+02:00'))
        ->withDateTo(DateTime::createFromFormat(DATE_ATOM, '2020-10-01T00:05:00+02:00'));
    $bulkData = $api->system('ABCDE')->statuses()->bulk()->measurements()
        ->get($measurementsCriteria);

Response

{
  "2020-10-01T00:00:00+02:00": {
    "10001": {
      "STATE": 0
    },
    "10002": {
      "STATE": 0
    }
  },
  "2020-10-01T00:05:00+02:00": {
    "10001": {
      "STATE": 1
    },
    "10002": {
      "STATE": 0
    }
  }
}

<?php
    /** @var MeasurementsBulkReader $bulkData */
    $bulkDataArray = $bulkData->getAsArray();
    echo $bulkDataArray['2020-10-01T00:00:00+02:00']['10001']['STATE'];// 0
    echo $bulkDataArray['2020-10-01T00:00:00+02:00']['10002']['STATE'];// 0
    echo $bulkDataArray['2020-10-01T00:05:00+02:00']['10001']['STATE'];// 1
    echo $bulkDataArray['2020-10-01T00:05:00+02:00']['10002']['STATE'];// 0

GET systems/<systemKey>/statuses/bulk/measurements

Path parameters

Name	Type	Description
systemKey `required`	`string`	Identification key of the system

Query parameters

Name	Type	Description
from `required`¹	`date`ǀ`datetime`	Start date
to `required`¹	`date`ǀ`datetime`	End date
format `optional`	`json`ǀ`csv`	Export format, defaults to `json`
deviceIds `optional`	`string`	Comma separated deviceIds
abbreviations `optional`	`string`	Comma separated abbreviations
includeInterval `optional`	`integer` `0`ǀ`1`	Defaults to `0`

¹ The maximum time span is 24 hours between from and to.

Options for CSV format

The following query parameters are valid only if format is csv
For response example in CSV format, please check HERE.

Name	Type	Description
delimiter	`comma`ǀ`semicolon`ǀ`colon`ǀ`tab`	The delimiter, defaults to `comma`
lineBreak	`LF`ǀ`CR`ǀ`CR/LF`	The line breaks, defaults to `LF`
decimalPoint	`dot`ǀ`comma`	The decimal point, defaults to `dot`
emptyPlaceholder	`text`, empty string by default, any text accepted	The place holder for empty value
precision	`integer`, accepts from 0 to 4	The decimal precision, defaults to `2`

Stringboxes

Get all stringbox devices

Request

curl 'https://api.meteocontrol.de/v2/systems/ABCDE/stringboxes'

<?php
    /** @var Stringbox[] $stringboxes */
    $stringboxes = $api->system('ABCDE')->stringboxes()->get();

Response

{
  "data": [
    {
      "id": "20001",
      "name": "stringbox1",
      "serial": "serial1"
    },
    {
      "id": "20002",
      "name": "stringbox2",
      "serial": "serial2"
    }
  ]
}

<?php
    /** @var Stringbox[] $stringboxes */
    echo $stringboxes[0]->id;// 20001
    echo $stringboxes[0]->name;// stringbox1
    echo $stringboxes[0]->serial;// serial1
    echo $stringboxes[1]->id;// 20002
    echo $stringboxes[1]->name;// stringbox2
    echo $stringboxes[1]->serial;// serial2

GET systems/<systemKey>/stringboxes

Path parameters

Name	Type	Description
systemKey `required`	`string`	Identification key of the system

Response

Property	Type	Description
id `fixed`	`string`	Stringbox device ID
name `fixed`	`string`	Custom name
serial `fixed`	`string`	Serial

Get single stringbox device

Request

curl 'https://api.meteocontrol.de/v2/systems/ABCDE/stringboxes/20001'

<?php
    /** @var StringboxDetail $stringbox */
    $stringbox = $api->system('ABCDE')->stringbox('20001')->get();

Response

{
  "data": {
    "id": "20001",
    "name": "stringbox1",
    "serial": "serial1",
    "scaleFactor": 1.32
  }
}

<?php
    /** @var StringboxDetail $stringbox */
    echo $stringbox->id;// 20001
    echo $stringbox->name;// stringbox1
    echo $stringbox->serial;// serial1
    echo $stringbox->scaleFactor;//1.32

GET systems/<systemKey>/stringboxes/<deviceId>

Path parameters

Name	Type	Description
systemKey `required`	`string`	Identification key of the system
deviceId `required`	`string`	Stringbox device ID

Response

Property	Type	Description
id `fixed`	`string`	Stringbox device ID
name `fixed`	`string`	Custom name
serial `fixed`	`string`	Serial
scaleFactor `fixed`	`number`	Normalization factor

Abbreviations

Request

curl 'https://api.meteocontrol.de/v2/systems/ABCDE/stringboxes/20001/abbreviations'

<?php
    /** @var string[] $abbreviations */
    $abbreviations = $api->system('ABCDE')->stringbox('20001')->abbreviations()->get();

Response

{
  "data": [
      "D_IN2",
      "I1",
      "I1_N"
  ]
}

<?php
    /** @var string[] $abbreviations */
    echo $abbreviations[0];// D_IN2
    echo $abbreviations[1];// I1
    echo $abbreviations[2];// I1_N

GET systems/<systemKey>/stringboxes/<deviceId>/abbreviations

Path parameters

Name	Type	Description
systemKey `required`	`string`	Identification key of the system
deviceId `required`	`string`	Stringbox device ID

Get single abbreviation

Request

curl 'https://api.meteocontrol.de/v2/systems/ABCDE/stringboxes/20001/abbreviations/I1'

<?php
    /** @var string[] $abbreviation */
    $abbreviation = $api->system('ABCDE')->stringbox('20001')->abbreviation('I1')->get();

Response

{
  "data": {
    "aggregation": "AVG",
    "precision": null,
    "description": "Current DC",
    "unit": "A",
    "active": true
  }
}

<?php
    /** @var Abbreviation $abbreviation */
    echo $abbreviation->aggregation;// AVG
    echo $abbreviation->precision;// null
    echo $abbreviation->description;// Current DC
    echo $abbreviation->unit;// A
    echo $abbreviation->active;// true

GET systems/<systemKey>/stringboxes/<deviceId>/abbreviations/<abbreviationId>

Returns an information object of an abbreviation.

Path parameters

Name	Type	Description
systemKey `required`	`string`	Identification key of the system
deviceId `required`	`string`	Stringbox device ID
abbreviationId `required`	`string`	Abbreviation ID

Response

Information object

Property	Type	Description
aggregation `fixed`	(`SUM`ǀ`AVG`ǀ`MAX`)	Aggregation method when requesting other resolutions than interval
precision `fixed`	`integer`	Number of decimal places
description `fixed`	`string`	Description
unit `fixed`	`string`	Unit
active `fixed`	`bool`	Active status

Measurements

Request

curl 'https://api.meteocontrol.de/v2/systems/ABCDE/stringboxes/20001/abbreviations/I1/measurements?from=2016-10-21T11:00:00+02:00&to=2016-10-21T11:05:00+02:00'

<?php
    $measurementsCriteria = (new MeasurementsCriteria())
        ->withDateFrom(DateTime::createFromFormat(DATE_ATOM, '2016-10-21T11:00:00+02:00'))
        ->withDateTo(DateTime::createFromFormat(DATE_ATOM, '2016-10-21T11:05:00+02:00'));
    /** @var DevicesMeasurement $measurements */
    $measurements = $api->system('ABCDE')->stringbox('20001')->abbreviation('I1')->measurements()
        ->get($measurementsCriteria);

Response

{
  "data": {
    "20001": {
      "I1": [
        {
          "timestamp": "2016-10-21T11:00:00+02:00",
          "value": 177.2
        },
        {
          "timestamp": "2016-10-21T11:05:00+02:00",
          "value": 157.2
        }
      ]
    }
  }
}

<?php
    /** @var DevicesMeasurement $measurements */
    echo $measurements['20001']['I1'][0]
        ->timestamp->format(DATE_ATOM);// 2016-10-21T11:00:00+02:00
    echo $measurements['20001']['I1'][0]->value;// 177.2
    echo $measurements['20001']['I1'][1]
        ->timestamp->format(DATE_ATOM);// 2016-10-21T11:05:00+02:00
    echo $measurements['20001']['I1'][1]->value;// 157.2

GET systems/<systemKey>/stringboxes/<deviceId>/abbreviations/<abbreviationId>/measurements

Path parameters

Name	Type	Description
systemKey `required`	`string`	Identification key of the system
deviceId `required`	`string`	Can contain up to 10 comma delimited stringbox device IDs
abbreviationId `required`	`string`	Can contain up to 5 comma delimited abbreviation IDs

Query parameters

Name	Type	Description
from `required`¹	`date`ǀ`datetime`	Start date
to `required`¹	`date`ǀ`datetime`	End date
resolution `optional`	(`minute²`ǀ`interval`ǀ`fifteen-minutes`ǀ`thirty-minutes`ǀ`hour`ǀ`day`ǀ`month`ǀ`year`)	Defaults to `interval`
includeInterval `optional`³	`integer` `0`ǀ`1`	Defaults to `0`

¹ The maximum time span between from and to varies depending on the resolution as listed below.

Resolution	Maximum time span
minute	1 day
interval	31 days
fifteen-minutes	31 days
thirty-minutes	31 days
hour	31 days
day	60 days
month	1 year
year	no limitation

² The option minute resolution is only supported by meteocontrol blue'Log XM / XC (Firmware 2.0 and higher)
³ Only for interval resolution

Response

Property	Type	Description
timestamp `fixed`	`datetime`	Timestamp
value `fixed`	`number`	Value

Bulk

Request

curl 'https://api.meteocontrol.de/v2/systems/ABCDE/stringboxes/bulk/measurements?from=2016-11-01T23:00:00+02:00&to=2016-11-01T23:05:00+02:00'

<?php
    $measurementsCriteria = (new MeasurementsCriteria())
        ->withDateFrom(DateTime::createFromFormat(DATE_ATOM, '2016-11-01T23:00:00+02:00'))
        ->withDateTo(DateTime::createFromFormat(DATE_ATOM, '2016-11-01T23:05:00+02:00'));
    $bulkData = $api->system('ABCDE')->stringboxes()->bulk()->measurements()
        ->get($measurementsCriteria);

Response

{
  "2016-11-01T23:00:00+02:00": {
    "20001": {
      "I1": 3.449,
      "I1_N": 0.43,
      "I2": 3.436,
      "I2_N": 0.43,
      "I3": 3.405,
      "I3_N": 0.42,
      "I4": 3.428,
      "I4_N": 0.43,
      "I5": 3.383,
      "I5_N": 0.42,
      "I6": 3.589,
      "I6_N": 0.45,
      "I7": 3.569,
      "I7_N": 0.45,
      "I8": 3.554,
      "I8_N": 0.44
    },
    "20002": {
      "D_IN2": null,
      "I1": 3.384,
      "I1_N": 0.42,
      "I10": 0,
      "I10_N": 0,
      "I11": 0,
      "I11_N": 0,
      "I12": 0,
      "I12_N": 0,
      "I13": 0,
      "I13_N": 0,
      "I14": 0,
      "I14_N": 0,
      "I2": 3.337,
      "I2_N": 0.42,
      "I3": 3.287,
      "I3_N": 0.41,
      "I4": 3.326,
      "I4_N": 0.41,
      "I5": 3.342,
      "I5_N": 0.42,
      "I6": 3.307,
      "I6_N": 0.41,
      "I7": 3.292,
      "I7_N": 0.41,
      "I8": 0.014,
      "I8_N": 0.01,
      "I9": 0,
      "I9_N": 0,
      "U_DC": 100,
      "STATE": null,
      "T1": 18.9
    },
    "20003": null,
    "20004": null,
    "20005": null,
    "20006": null,
    "20007": null,
    "20008": null,
    "20009": null,
    "20010": null,
    "20011": null,
    "20012": null,
    "20013": null,
    "20014": null,
    "20015": null,
    "20016": null,
    "20017": null,
    "20018": null,
    "20019": null,
    "20020": null
  },
  "2016-11-01T23:05:00+02:00": {
    "20001": {
      "I1": 3.913,
      "I1_N": 0.49,
      "I2": 3.894,
      "I2_N": 0.49,
      "I3": 3.85,
      "I3_N": 0.48,
      "I4": 3.882,
      "I4_N": 0.48,
      "I5": 3.827,
      "I5_N": 0.48,
      "I6": 4.053,
      "I6_N": 0.51,
      "I7": 4.043,
      "I7_N": 0.5,
      "I8": 4.031,
      "I8_N": 0.5
    },
    "20002": {
      "I1": 3.869,
      "I1_N": 0.48,
      "I2": 3.817,
      "I2_N": 0.48,
      "I3": 3.755,
      "I3_N": 0.47,
      "I4": 3.805,
      "I4_N": 0.47,
      "I5": 3.819,
      "I5_N": 0.48,
      "I6": 3.777,
      "I6_N": 0.47,
      "I7": 3.764,
      "I7_N": 0.47,
      "I8": 0.014,
      "I8_N": 0.01
    }
  }
}

<?php
    /** @var MeasurementsBulkReader $bulkData */
    $bulkDataArray = $bulkData->getAsArray();
    echo $bulkDataArray['2016-11-01T23:00:00+02:00']['20001']['I1'];// 3.449
    echo $bulkDataArray['2016-11-01T23:00:00+02:00']['20001']['I1_N'];// 0.42
    echo $bulkDataArray['2016-11-01T23:00:00+02:00']['20002']['I1'];// 3.384
    echo $bulkDataArray['2016-11-01T23:00:00+02:00']['20002']['I1_N'];// 0.43
    echo $bulkDataArray['2016-11-01T23:05:00+02:00']['20001']['I1'];// 3.913
    echo $bulkDataArray['2016-11-01T23:05:00+02:00']['20001']['I1_N'];// 0.49
    echo $bulkDataArray['2016-11-01T23:05:00+02:00']['20002']['I1'];// 3.869
    echo $bulkDataArray['2016-11-01T23:05:00+02:00']['20002']['I1_N'];// 0.48

GET systems/<systemKey>/stringboxes/bulk/measurements

Path parameters

Name	Type	Description
systemKey `required`	`string`	Identification key of the system

Query parameters

Name	Type	Description
from `required`¹	`date`ǀ`datetime`	Start date
to `required`¹	`date`ǀ`datetime`	End date
format `optional`	`json`ǀ`csv`	Export format, defaults to `json`
resolution `optional`	(`minute²`ǀ`interval`ǀ`fifteen-minutes`ǀ`thirty-minutes`ǀ`hour`ǀ`day`)	Defaults to `interval`
activeOnly `optional`	`integer` `0`ǀ`1`	Export active strings only, defaults to `0`
deviceIds `optional`	`string`	Comma separated deviceIds
abbreviations `optional`	`string`	Comma separated abbreviations
includeInterval `optional`³	`integer` `0`ǀ`1`	Defaults to `0`

Options for CSV format

The following query parameters are valid only if format is csv
For response example in CSV format, please check HERE.

Name	Type	Description
delimiter	`comma`ǀ`semicolon`ǀ`colon`ǀ`tab`	The delimiter, defaults to `comma`
lineBreak	`LF`ǀ`CR`ǀ`CR/LF`	The line breaks, defaults to `LF`
decimalPoint	`dot`ǀ`comma`	The decimal point, defaults to `dot`
emptyPlaceholder	`text`, empty string by default, any text accepted	The place holder for empty value
precision	`integer`, accepts from 0 to 4	The decimal precision, defaults to `2`

Batteries

Get all batteries

Request

curl 'https://api.meteocontrol.de/v2/systems/ABCDE/batteries'

<?php
    /** @var Battery[] $batteries */
    $batteries = $api->system('ABCDE')->batteries()->get();

Response

{
    "data": [
        {
            "id": "145146",
            "name": "",
            "uid": "bat1"
        },
        {
            "id": "145147",
            "name": "",
            "uid": "bat2"
        }
    ]
}

<?php
    /** @var Battery[] $batteries */
    echo $batteries[0]->id;// 145146
    echo $batteries[0]->name;
    echo $batteries[0]->uid;// bat1
    echo $batteries[1]->id;// 145147
    echo $batteries[1]->name;
    echo $batteries[1]->uid;// bat2

GET systems/<systemKey>/batteries

Path parameters

Name	Type	Description
systemKey `required`	`string`	Identification key of the system

Response

Property	Type	Description
id `fixed`	`string`	Battery device ID
name `fixed`	`string`	Custom name
uid `fixed`	`string`ǀ`null`	UID

Get single battery

Request

curl 'https://api.meteocontrol.de/v2/systems/ABCDE/batteries/145146'

<?php
    /** @var BatteryDetail $battery */
    $battery = $api->system('ABCDE')->battery('145146')->get();

Response

{
  "data": {
    "id": "145146",
    "name": "",
    "uid": "bat1",
    "address": "bat1",
    "firmware": "1.0"
  }
}

<?php
    /** @var BatteryDetail $battery */
    echo $battery->id;// 145146
    echo $battery->name;
    echo $battery->uid;// bat1
    echo $battery->address;// bat1
    echo $battery->firmware;// 1.0

GET systems/<systemKey>/batteries/<deviceId>

Path parameters

Name	Type	Description
systemKey `required`	`string`	Identification key of the system
deviceId `required`	`string`	Battery device ID

Response

Property	Type	Description
id `fixed`	`string`	Battery device ID
name `fixed`	`string`	Custom name
uid `fixed`	`string`ǀ`null`	UID
address `fixed`	`string`ǀ`null`	Address
firmware `fixed`	`string`ǀ`null`	Firmware

Abbreviations

Request

curl 'https://api.meteocontrol.de/v2/systems/ABCDE/batteries/145146/abbreviations'

<?php
    /** @var string[] $abbreviations */
    $abbreviations = $api->system('ABCDE')->battery('145146')->abbreviations()->get();

Response

{
  "data":  [
    "B_CHARGE_LEVEL",
    "B_E_EXP",
    "B_E_IMP",
    "T1"
  ]
}

<?php
    /** @var string[] $abbreviations */
    echo $abbreviations[0];// B_CHARGE_LEVEL
    echo $abbreviations[1];// B_E_EXP
    echo $abbreviations[2];// B_E_IMP
    echo $abbreviations[3];// T1

GET systems/<systemKey>/batteries/<deviceId>/abbreviations

Path parameters

Name	Type	Description
systemKey `required`	`string`	Identification key of the system
deviceId `required`	`string`	Battery device ID

Get single abbreviation

Request

curl 'https://api.meteocontrol.de/v2/systems/ABCDE/batteries/145146/abbreviations/B_CHARGE_LEVEL'

<?php
    /** @var Abbreviation $abbreviation */
    $abbreviation = $api->system('ABCDE')->battery('145146')->abbreviation('B_CHARGE_LEVEL')->get();

Response

{
  "data": {
    "aggregation": "AVG",
    "precision": 2,
    "description": "Charging status",
    "unit": "%"
  }
}

<?php
    /** @var Abbreviation $abbreviation */
    echo $abbreviation->aggregation;// AVG
    echo $abbreviation->precision;// 2
    echo $abbreviation->description;// Charging status
    echo $abbreviation->unit;// %

GET systems/<systemKey>/batteries/<deviceId>/abbreviations/<abbreviationId>

Returns an information object of an abbreviation.

Path parameters

Name	Type	Description
systemKey `required`	`string`	Identification key of the system
deviceId `required`	`string`	Battery device ID
abbreviationId `required`	`string`	Abbreviation ID

Response

Information object

Property	Type	Description
aggregation `fixed`	(`SUM`ǀ`AVG`ǀ`MAX`)	Aggregation method when requesting other resolutions than interval
precision `fixed`	`integer`	Number of decimal places
description `fixed`	`string`	Description
unit `fixed`	`string`	Unit

Measurements

Request

curl 'https://api.meteocontrol.de/v2/systems/ABCDE/batteries/145146/abbreviations/B_CHARGE_LEVEL/measurements?from=2016-11-01T11:00:00+02:00&to=2016-11-01T11:05:00+02:00'

<?php
    $measurementsCriteria = (new MeasurementsCriteria())
        ->withDateFrom(DateTime::createFromFormat(DATE_ATOM, '2016-11-01T11:00:00+02:00'))
        ->withDateTo(DateTime::createFromFormat(DATE_ATOM, '2016-11-01T11:05:00+02:00'));
    /** @var DevicesMeasurement $measurements */
    $measurements = $api->system('ABCDE')->battery('145146')->abbreviation('B_CHARGE_LEVEL')->measurements()
        ->get($measurementsCriteria);

Response

{
  "data": {
    "145146": {
      "B_CHARGE_LEVEL": [
        {
          "timestamp": "2016-11-01T11:00:00+02:00",
          "value": 80.762
        },
        {
          "timestamp": "2016-11-01T11:05:00+02:00",
          "value": 80.862
        }
      ]
    }
  }
}

<?php
    /** @var DevicesMeasurement $measurements */
    echo $measurements['145146']['B_CHARGE_LEVEL'][0]
        ->timestamp->format(DATE_ATOM);// 2016-11-01T11:00:00+02:00
    echo $measurements['145146']['B_CHARGE_LEVEL'][0]->value;// 80.762
    echo $measurements['145146']['B_CHARGE_LEVEL'][1]
        ->timestamp->format(DATE_ATOM);// 2016-11-01T11:05:00+02:00
    echo $measurements['145146']['B_CHARGE_LEVEL'][1]->value;// 80.862

GET systems/<systemKey>/batteries/<deviceId>/abbreviations/<abbreviationId>/measurements

Path parameters

Name	Type	Description
systemKey `required`	`string`	Identification key of the system
deviceId `required`	`string`	Can contain up to 10 comma delimited battery device IDs
abbreviationId `required`	`string`	Can contain up to 5 comma delimited abbreviation IDs

Query parameters

Name	Type	Description
from `required`¹	`date`ǀ`datetime`	Start date
to `required`¹	`date`ǀ`datetime`	End date
resolution `optional`	(`minute²`ǀ`interval`ǀ`fifteen-minutes`ǀ`thirty-minutes`ǀ`hour`ǀ`day`ǀ`month`ǀ`year`)	Defaults to `interval`
includeInterval `optional`³	`integer` `0`ǀ`1`	Defaults to `0`

¹ The maximum time span between from and to varies depending on the resolution as listed below.

Resolution	Maximum time span
minute	1 day
interval	31 days
fifteen-minutes	31 days
thirty-minutes	31 days
hour	31 days
day	60 days
month	1 year
year	no limitation

² The option minute resolution is only supported by meteocontrol blue'Log XM / XC (Firmware 2.0 and higher)
³ Only for interval resolution

Response

Property	Type	Description
timestamp `fixed`	`datetime`	Timestamp
value `fixed`	`number`	Value
interval `optional`	`number`	Interval, in seconds

Bulk

Request

curl 'https://api.meteocontrol.de/v2/systems/ABCDE/batteries/bulk/measurements?from=2016-10-10T11:00:00+02:00&to=2016-10-10T11:15:00+02:00'

<?php
    $measurementsCriteria = (new MeasurementsCriteria())
        ->withDateFrom(DateTime::createFromFormat(DATE_ATOM, '2016-10-10T11:00:00+02:00'))
        ->withDateTo(DateTime::createFromFormat(DATE_ATOM, '2016-10-10T11:15:00+02:00'));
    $bulkData = $api->system('ABCDE')->batteries()->bulk()->measurements()
        ->get($measurementsCriteria);

Response

{
  "2016-10-10T11:00:00+02:00": {
    "145146": {
      "B_CHARGE_LEVEL": 80.762,
      "B_E_EXP": 1347.7619999999999,
      "B_E_IMP": 29.155999999999999,
      "T1": 30.789000000000001
    },
    "145147": {
      "B_CHARGE_LEVEL": 80.772000000000006,
      "B_E_EXP": 1347.7719999999999,
      "B_E_IMP": 29.166,
      "T1": 30.798999999999999
    }
  },
  "2016-10-10T11:05:00+02:00": {
    "145146": {
      "B_CHARGE_LEVEL": 80.781999999999996,
      "B_E_EXP": 1347.7819999999999,
      "B_E_IMP": 29.175999999999998,
      "T1": 30.809000000000001
    },
    "145147": {
      "B_CHARGE_LEVEL": 80.792000000000002,
      "B_E_EXP": 1347.7919999999999,
      "B_E_IMP": 29.186,
      "T1": 30.818999999999999
    }
  },
  "2016-10-10T11:10:00+02:00": {
    "145146": {
      "B_CHARGE_LEVEL": 80.802000000000007,
      "B_E_EXP": 1347.8019999999999,
      "B_E_IMP": 29.196000000000002,
      "T1": 30.829000000000001
    },
    "145147": {
      "B_CHARGE_LEVEL": 80.811999999999998,
      "B_E_EXP": 1347.8119999999999,
      "B_E_IMP": 29.206,
      "T1": 30.838999999999999
    }
  },
  "2016-10-10T11:15:00+02:00": {
    "145146": {
      "B_CHARGE_LEVEL": 80.822000000000003,
      "B_E_EXP": 1347.8219999999999,
      "B_E_IMP": 29.216000000000001,
      "T1": 30.849
    },
    "145147": {
      "B_CHARGE_LEVEL": 80.831999999999994,
      "B_E_EXP": 1347.8320000000001,
      "B_E_IMP": 29.225999999999999,
      "T1": 30.859000000000002
    }
  }
}

<?php
    /** @var MeasurementsBulkReader $bulkData */
    $bulkDataArray = $bulkData->getAsArray();
    echo $bulkDataArray['2016-10-10T11:00:00+02:00']['145146']['B_CHARGE_LEVEL'];// 80.762
    echo $bulkDataArray['2016-10-10T11:00:00+02:00']['145146']['B_E_EXP'];// 1347.762
    echo $bulkDataArray['2016-10-10T11:00:00+02:00']['145147']['B_CHARGE_LEVEL'];// 80.772
    echo $bulkDataArray['2016-10-10T11:00:00+02:00']['145147']['B_E_EXP'];// 1347.772
    echo $bulkDataArray['2016-10-10T11:15:00+02:00']['145146']['B_CHARGE_LEVEL'];// 80.822
    echo $bulkDataArray['2016-10-10T11:15:00+02:00']['145146']['B_E_EXP'];// 1347.822
    echo $bulkDataArray['2016-10-10T11:15:00+02:00']['145147']['B_CHARGE_LEVEL'];// 80.832
    echo $bulkDataArray['2016-10-10T11:15:00+02:00']['145147']['B_E_EXP'];// 1347.832

GET systems/<systemKey>/batteries/bulk/measurements

Path parameters

Name	Type	Description
systemKey `required`	`string`	Identification key of the system

Query parameters

Name	Type	Description
from `required`¹	`date`ǀ`datetime`	Start date
to `required`¹	`date`ǀ`datetime`	End date
format `optional`	`json`ǀ`csv`	Export format, defaults to `json`
resolution `optional`	(`minute²`ǀ`interval`ǀ`fifteen-minutes`ǀ`thirty-minutes`ǀ`hour`ǀ`day`)	Defaults to `interval`
deviceIds `optional`	`string`	Comma separated deviceIds
abbreviations `optional`	`string`	Comma separated abbreviations
includeInterval `optional`³	`integer` `0`ǀ`1`	Defaults to `0`

Options for CSV format

The following query parameters are valid only if format is csv
For response example in CSV format, please check HERE.

Name	Type	Description
delimiter	`comma`ǀ`semicolon`ǀ`colon`ǀ`tab`	The delimiter, defaults to `comma`
lineBreak	`LF`ǀ`CR`ǀ`CR/LF`	The line breaks, defaults to `LF`
decimalPoint	`dot`ǀ`comma`	The decimal point, defaults to `dot`
emptyPlaceholder	`text`, empty string by default, any text accepted	The place holder for empty value
precision	`integer`, accepts from 0 to 4	The decimal precision, defaults to `2`

Power plant controllers

Get all power plant controllers

Request

curl 'https://api.meteocontrol.de/v2/systems/ABCDE/power-plant-controllers'

<?php
    /** @var PowerPlantController[] $powerPlantControllers */
    $powerPlantControllers = $api->system('ABCDE')->powerPlantControllers()->get();

Response

{
    "data": [
        {
            "id": "163784",
            "name": "ppc-5bbc370ddb808",
            "uid": "ppc-5bbc370ddb808"
        }
    ]
}

<?php
    /** @var PowerPlantController[] $powerPlantControllers */
    echo $powerPlantControllers[0]->id;// 163784
    echo $powerPlantControllers[0]->name;// ppc-5bbc370ddb808
    echo $powerPlantControllers[0]->uid;// ppc-5bbc370ddb808

GET systems/<systemKey>/power-plant-controllers

Path parameters

Name	Type	Description
systemKey `required`	`string`	Identification key of the system

Response

Property	Type	Description
id `fixed`	`string`	Power plant controller device ID
name `fixed`	`string`	Custom name
uid `fixed`	`string`ǀ`null`	UID

Get single power plant controller

Request

curl 'https://api.meteocontrol.de/v2/systems/ABCDE/power-plant-controllers/163784'

<?php
    /** @var PowerPlantControllerDetail $powerPlantController */
    $powerPlantController = $api->system('ABCDE')->powerPlantController('163784')->get();

Response

{
  "data": {
    "id": "163784",
    "name": "ppc-5bbc370ddb808",
    "uid": "ppc-5bbc370ddb808",
    "address": "ppc-5bbc370ddb808",
    "firmware": null
  }
}

<?php
    /** @var PowerPlantControllerDetail $powerPlantController */
    echo $powerPlantController->id;// 163784
    echo $powerPlantController->name;// ppc-5bbc370ddb808
    echo $powerPlantController->uid;// ppc-5bbc370ddb808
    echo $powerPlantController->address;// ppc-5bbc370ddb808
    echo $powerPlantController->firmware;// null

GET systems/<systemKey>/power-plant-controllers/<deviceId>

Path parameters

Name	Type	Description
systemKey `required`	`string`	Identification key of the system
deviceId `required`	`string`	Power plant controller device ID

Response

Property	Type	Description
id `fixed`	`string`	Power plant controller device ID
name `fixed`	`string`	Custom name
uid `fixed`	`string`ǀ`null`	UID
address `fixed`	`string`ǀ`null`	Address
firmware `fixed`	`string`ǀ`null`	Firmware

Abbreviations

Request

curl 'https://api.meteocontrol.de/v2/systems/ABCDE/power-plant-controllers/163784/abbreviations'

<?php
    /** @var string[] $abbreviations */
    $abbreviations = $api->system('ABCDE')->powerPlantController('163784')->abbreviations()->get();

Response

{
  "data": [
    "PPC_P_AC",
    "PPC_P_AC_AVAIL",
    "PPC_P_AC_GRIDOP_MAX",
    "PPC_P_AC_INV",
    "PPC_P_AC_RPC_MAX",
    "PPC_P_SET_GRIDOP_ABS",
    "PPC_P_SET_GRIDOP_REL",
    "PPC_P_SET_REL",
    "PPC_P_SET_RPC_REL",
    "PPC_PF",
    "PPC_PF_SET",
    "PPC_Q_AC",
    "PPC_Q_AC_AVAIL",
    "PPC_Q_SET_ABS",
    "PPC_Q_SET_REL"
  ]
}

<?php
    /** @var string[] $abbreviations */
    echo $abbreviations[0];// PPC_P_AC
    echo $abbreviations[1];// PPC_P_AC_AVAIL
    echo $abbreviations[2];// PPC_P_AC_GRIDOP_MAX
    echo $abbreviations[3];// PPC_P_AC_INV
    echo $abbreviations[4];// PPC_P_AC_RPC_MAX
    echo $abbreviations[5];// PPC_P_SET_GRIDOP_ABS
    echo $abbreviations[6];// PPC_P_SET_GRIDOP_REL
    echo $abbreviations[7];// PPC_P_SET_REL
    echo $abbreviations[8];// PPC_P_SET_RPC_REL
    echo $abbreviations[9];// PPC_PF
    echo $abbreviations[10];// PPC_PF_SET
    echo $abbreviations[11];// PPC_Q_AC
    echo $abbreviations[12];// PPC_Q_AC_AVAIL
    echo $abbreviations[13];// PPC_Q_SET_ABS
    echo $abbreviations[14];// PPC_Q_SET_REL

GET systems/<systemKey>/power-plant-controllers/<deviceId>/abbreviations

Path parameters

Name	Type	Description
systemKey `required`	`string`	Identification key of the system
deviceId `required`	`string`	Power plant controller device ID

Get single abbreviation

Request

curl 'https://api.meteocontrol.de/v2/systems/ABCDE/power-plant-controllers/145146/abbreviations/PPC_P_AC'

<?php
    /** @var Abbreviation $abbreviation */
    $abbreviation = $api->system('ABCDE')->powerPlantController('145146')->abbreviation('PPC_P_AC')->get();

Response

{
  "data": {
    "aggregation": "AVG",
    "precision": 3,
    "description": "Actual active power",
    "unit": "W"
  }
}

<?php
    /** @var Abbreviation $abbreviation */
    echo $abbreviation->aggregation;// AVG
    echo $abbreviation->precision;// 3
    echo $abbreviation->description;// Actual active power
    echo $abbreviation->unit;// W

GET systems/<systemKey>/power-plant-controllers/<deviceId>/abbreviations/<abbreviationId>

Returns an information object of an abbreviation.

Path parameters

Name	Type	Description
systemKey `required`	`string`	Identification key of the system
deviceId `required`	`string`	Power plant controller device ID
abbreviationId `required`	`string`	Abbreviation ID

Response

Information object

Property	Type	Description
aggregation `fixed`	(`SUM`ǀ`AVG`ǀ`MAX`)	Aggregation method when requesting other resolutions than interval
precision `fixed`	`integer`	Number of decimal places
description `fixed`	`string`	Description
unit `fixed`	`string`	Unit

Measurements

Request

curl 'https://api.meteocontrol.de/v2/systems/ABCDE/power-plant-controllers/163784/abbreviations/PPC_P_AC/measurements?from=2016-10-29T11:00:00+02:00&to=2016-10-29T11:05:00+02:00'

<?php
    $measurementsCriteria = (new MeasurementsCriteria())
        ->withDateFrom(DateTime::createFromFormat(DATE_ATOM, '2016-10-29T11:00:00+02:00'))
        ->withDateTo(DateTime::createFromFormat(DATE_ATOM, '2016-10-29T11:05:00+02:00'));
    /** @var DevicesMeasurement $measurements */
    $measurements = $api->system('ABCDE')->powerPlantController('163784')->abbreviation('PPC_P_AC')->measurements()
        ->get($measurementsCriteria);

Response

{
  "data": {
    "163784": {
      "PPC_P_AC": [
        {
          "timestamp": "2016-10-29T11:00:00+02:00",
          "value": 41.73
        },
        {
          "timestamp": "2016-10-29T11:05:00+02:00",
          "value": 60.34
        }
      ]
    }
  }
}

<?php
    /** @var DevicesMeasurement $measurements */
    echo $measurements['163784']['PPC_P_AC'][0]
        ->timestamp->format(DATE_ATOM);// 2016-10-29T11:00:00+02:00
    echo $measurements['163784']['PPC_P_AC'][0]->value;// 41.73
    echo $measurements['163784']['PPC_P_AC'][1]
        ->timestamp->format(DATE_ATOM);// 2016-10-29T11:05:00+02:00
    echo $measurements['163784']['PPC_P_AC'][1]->value;// 60.34

GET systems/<systemKey>/power-plant-controllers/<deviceId>/abbreviations/<abbreviationId>/measurements

Path parameters

Name	Type	Description
systemKey `required`	`string`	Identification key of the system
deviceId `required`	`string`	Can contain up to 10 comma delimited power plant controller device IDs
abbreviationId `required`	`string`	Can contain up to 5 comma delimited abbreviation IDs

Query parameters

Name	Type	Description
from `required`¹	`date`ǀ`datetime`	Start date
to `required`¹	`date`ǀ`datetime`	End date
resolution `optional`	(`minute²`ǀ`interval`ǀ`fifteen-minutes`ǀ`thirty-minutes`ǀ`hour`ǀ`day`ǀ`month`ǀ`year`)	Defaults to `interval`
includeInterval `optional`³	`integer` `0`ǀ`1`	Defaults to `0`

¹ The maximum time span between from and to varies depending on the resolution as listed below.

Resolution	Maximum time span
minute	1 day
interval	31 days
fifteen-minutes	31 days
thirty-minutes	31 days
hour	31 days
day	60 days
month	1 year
year	no limitation

² The option minute resolution is only supported by meteocontrol blue'Log XM / XC (Firmware 2.0 and higher)
³ Only for interval resolution

Response

Property	Type	Description
timestamp `fixed`	`datetime`	Timestamp
value `fixed`	`number`	Value

Bulk

Request

curl 'https://api.meteocontrol.de/v2/systems/ABCDE/power-plant-controllers/bulk/measurements?from=2016-10-29T18:00:00+02:00&to=2016-10-29T18:15:00+02:00'

<?php
    $measurementsCriteria = (new MeasurementsCriteria())
        ->withDateFrom(DateTime::createFromFormat(DATE_ATOM, '2016-10-29T18:00:00+02:00'))
        ->withDateTo(DateTime::createFromFormat(DATE_ATOM, '2016-10-29T18:15:00+02:00'));
    $bulkData = $api->system('ABCDE')->powerPlantControllers()->bulk()->measurements()
        ->get($measurementsCriteria);

Response

{
  "2016-10-29T18:00:00+02:00": {
    "163784": {
      "PPC_P_AC_INV": 52.350000000000001,
      "PPC_P_AC_AVAIL": 79.859999999999999,
      "PPC_Q_AC_AVAIL": 13.5,
      "PPC_P_SET_GRIDOP_REL": 77.599999999999994,
      "PPC_P_SET_MANUAL_REL":null,
      "PPC_P_SET_GRIDOP_ABS": 92.299999999999997,
      "PPC_P_SET_RPC_REL": 38.399999999999999,
      "PPC_P_SET_STATIC_REL": null,
      "PPC_P_SET_REL": 52.899999999999999,
      "PPC_PF_SET": null,
      "PPC_Q_SET_ABS": 83.599999999999994,
      "PPC_P_AC_GRIDOP_MAX": 55.350000000000001,
      "PPC_P_AC_RPC_MAX": 88.170000000000002,
      "PPC_P_AC": 70.650000000000006,
      "PPC_Q_AC": 26.73,
      "PPC_PF": 4.2000000000000002,
      "PPC_Q_SET_REL": 37
    }
  },
  "2016-10-29T18:05:00+02:00": {
    "163784": {
      "PPC_P_AC_INV": 72.200000000000003,
      "PPC_P_AC_AVAIL": 37.450000000000003,
      "PPC_Q_AC_AVAIL": 32.299999999999997,
      "PPC_P_SET_GRIDOP_REL": 52.299999999999997,
      "PPC_P_SET_MANUAL_REL": null,
      "PPC_P_SET_GRIDOP_ABS": 85.299999999999997,
      "PPC_P_SET_RPC_REL": 1.3999999999999999,
      "PPC_P_SET_STATIC_REL":null,
      "PPC_P_SET_REL": 77.400000000000006,
      "PPC_PF_SET": null,
      "PPC_Q_SET_ABS": 85.900000000000006,
      "PPC_P_AC_GRIDOP_MAX": 42.770000000000003,
      "PPC_P_AC_RPC_MAX": 35.140000000000001,
      "PPC_P_AC": 42.43,
      "PPC_Q_AC": 91.590000000000003,
      "PPC_PF": 8.3000000000000007,
      "PPC_Q_SET_REL": 39.100000000000001
    }
  },
  "2016-10-29T18:10:00+02:00": {
    "163784": {
      "PPC_P_AC_INV": 28.780000000000001,
      "PPC_P_AC_AVAIL": 23.989999999999998,
      "PPC_Q_AC_AVAIL": 52.100000000000001,
      "PPC_P_SET_GRIDOP_REL": 50.299999999999997,
      "PPC_P_SET_MANUAL_REL": null,
      "PPC_P_SET_GRIDOP_ABS": 91.5,
      "PPC_P_SET_RPC_REL": 56.700000000000003,
      "PPC_P_SET_STATIC_REL": null,
      "PPC_P_SET_REL": 4.2000000000000002,
      "PPC_PF_SET": null,
      "PPC_Q_SET_ABS": 33.600000000000001,
      "PPC_P_AC_GRIDOP_MAX": 62.939999999999998,
      "PPC_P_AC_RPC_MAX": 60.119999999999997,
      "PPC_P_AC": 12.720000000000001,
      "PPC_Q_AC": 57.43,
      "PPC_PF": 1.3999999999999999,
      "PPC_Q_SET_REL": 22.100000000000001
    }
  },
  "2016-10-29T18:15:00+02:00": {
    "163784": {
      "PPC_P_AC_INV": 17.059999999999999,
      "PPC_P_AC_AVAIL": 47.579999999999998,
      "PPC_Q_AC_AVAIL": 53.100000000000001,
      "PPC_P_SET_GRIDOP_REL": 13.6,
      "PPC_P_SET_MANUAL_REL": null,
      "PPC_P_SET_GRIDOP_ABS": 90,
      "PPC_P_SET_RPC_REL": 85.400000000000006,
      "PPC_P_SET_STATIC_REL": null,
      "PPC_P_SET_REL": 3.2999999999999998,
      "PPC_PF_SET": 1.2,
      "PPC_Q_SET_ABS": 65.400000000000006,
      "PPC_P_AC_GRIDOP_MAX": 23.960000000000001,
      "PPC_P_AC_RPC_MAX": 76.609999999999999,
      "PPC_P_AC": 62.740000000000002,
      "PPC_Q_AC": 99.480000000000004,
      "PPC_PF": 7.2000000000000002,
      "PPC_Q_SET_REL": null
    }
  }
}

<?php
    /** @var MeasurementsBulkReader $bulkData */
    $bulkDataArray = $bulkData->getAsArray();
    echo $bulkDataArray['2016-10-29T18:00:00+02:00']['163784']['PPC_P_AC_INV'];// 52.350000000000001
    echo $bulkDataArray['2016-10-29T18:00:00+02:00']['163784']['PPC_Q_SET_ABS'];// 83.599999999999994
    echo $bulkDataArray['2016-10-29T18:10:00+02:00']['163784']['PPC_P_AC_INV'];// 28.780000000000001
    echo $bulkDataArray['2016-10-29T18:10:00+02:00']['163784']['PPC_Q_SET_ABS'];// 33.600000000000001

GET systems/<systemKey>/power-plant-controllers/bulk/measurements

Path parameters

Name	Type	Description
systemKey `required`	`string`	Identification key of the system

Query parameters

Name	Type	Description
from `required`¹	`date`ǀ`datetime`	Start date
to `required`¹	`date`ǀ`datetime`	End date
format `optional`	`json`ǀ`csv`	Export format, defaults to `json`
resolution `optional`	(`minute²`ǀ`interval`ǀ`fifteen-minutes`ǀ`thirty-minutes`ǀ`hour`ǀ`day`)	Defaults to `interval`
deviceIds `optional`	`string`	Comma separated deviceIds
abbreviations `optional`	`string`	Comma separated abbreviations
includeInterval `optional`³	`integer` `0`ǀ`1`	Defaults to `0`

Options for CSV format

The following query parameters are valid only if format is csv
For response example in CSV format, please check HERE.

Name	Type	Description
delimiter	`comma`ǀ`semicolon`ǀ`colon`ǀ`tab`	The delimiter, defaults to `comma`
lineBreak	`LF`ǀ`CR`ǀ`CR/LF`	The line breaks, defaults to `LF`
decimalPoint	`dot`ǀ`comma`	The decimal point, defaults to `dot`
emptyPlaceholder	`text`, empty string by default, any text accepted	The place holder for empty value
precision	`integer`, accepts from 0 to 4	The decimal precision, defaults to `2`

Trackers

Get all trackers

Request

curl 'https://api.meteocontrol.de/v2/systems/ABCDE/trackers'

<?php
    /** @var Tracker[] $trackers */
    $trackers = $api->system('ABCDE')->trackers()->get();

Response

{
  "data": [
    {
      "id": "30001",
      "name": "Tracker 1",
      "uid": "1"
    },
    {
      "id": "30002",
      "name": "Tracker 2",
      "uid": "2"
    }
  ]
}

<?php
    /** @var Tracker[] $trackers */
    echo $trackers[0]->id;// 30001
    echo $trackers[0]->name;// Tracker 1
    echo $trackers[0]->uid;// 1
    echo $trackers[1]->id;// 30002
    echo $trackers[1]->name;// Tracker 2
    echo $trackers[1]->uid;// 2

GET systems/<systemKey>/trackers

Path parameters

Name	Type	Description
systemKey `required`	`string`	Identification key of the system

Response

Property	Type	Description
id `fixed`	`string`	Tracker device ID
name `fixed`	`string`	Custom name
uid `fixed`	`string`ǀ`null`	UID

Get single tracker

Request

curl 'https://api.meteocontrol.de/v2/systems/ABCDE/trackers/30001'

<?php
    /** @var TrackerDetail $tracker */
    $tracker = $api->system('ABCDE')->tracker('30001')->get();

Response

{
  "data": {
    "id": "30001",
    "name": "Tracker 1",
    "uid": "1",
    "address": "1",
    "vendor": "IDEEMATEC",
    "model": "HORIZON 2",
    "firmware": "1.0"
  }
}

<?php
    /** @var TrackerDetail $tracker */
    echo $tracker->id;// 30001
    echo $tracker->name;// Tracker 1
    echo $tracker->uid;// 1
    echo $tracker->address;// 1
    echo $tracker->vendor;// IDEEMATEC
    echo $tracker->model;// HORIZON 2
    echo $tracker->firmware;// 1.0

GET systems/<systemKey>/trackers/<deviceId>

Path parameters

Name	Type	Description
systemKey `required`	`string`	Identification key of the system
deviceId `required`	`string`	Tracker device ID

Response

Property	Type	Description
id `fixed`	`string`	Tracker device ID
name `fixed`	`string`	Custom name
uid `fixed`	`string`ǀ`null`	UID
address `fixed`	`string`ǀ`null`	Address
vendor `fixed`	`string`ǀ`null`	Vendor
model `fixed`	`string`ǀ`null`	Model
firmware `fixed`	`string`ǀ`null`	Firmware

Abbreviations

Request

curl 'https://api.meteocontrol.de/v2/systems/ABCDE/trackers/30001/abbreviations'

<?php
    /** @var string[] $abbreviations */
    $abbreviations = $api->system('ABCDE')->tracker('30001')->abbreviations()->get();

Response

{
  "data": [
    "ELEVATION",
    "ELEVATION_TARGET",
    "QS_CI",
    "QS_RX",
    "QS_TX",
    "STATE1"
  ]
}

<?php
    /** @var string[] $abbreviations */
    echo $abbreviations[0];// ELEVATION
    echo $abbreviations[1];// ELEVATION_TARGET
    echo $abbreviations[2];// QS_CI
    echo $abbreviations[3];// QS_RX
    echo $abbreviations[4];// QS_TX
    echo $abbreviations[5];// STATE1

GET systems/<systemKey>/trackers/<deviceId>/abbreviations

Path parameters

Name	Type	Description
systemKey `required`	`string`	Identification key of the system
deviceId `required`	`string`	Tracker device ID

Get single abbreviation

Request

curl 'https://api.meteocontrol.de/v2/systems/ABCDE/trackers/30001/abbreviations/ELEVATION'

<?php
    /** @var Abbreviation $abbreviation */
    $abbreviation = $api->system('ABCDE')->tracker('30001')->abbreviation('ELEVATION')->get();

Response

{
  "data": {
    "aggregation": "AVG",
    "precision": 0,
    "description": "Tilt, actual value",
    "unit": "°"
  }
}

<?php
    /** @var Abbreviation $abbreviation */
    echo $abbreviation->aggregation;// AVG
    echo $abbreviation->precision;// 0
    echo $abbreviation->description;// Tilt, actual value
    echo $abbreviation->unit;// °

GET systems/<systemKey>/trackers/<deviceId>/abbreviations/<abbreviationId>

Returns an information object of an abbreviation.

Path parameters

Name	Type	Description
systemKey `required`	`string`	Identification key of the system
deviceId `required`	`string`	Tracker device ID
abbreviationId `required`	`string`	Abbreviation ID

Response

Information object

Property	Type	Description
aggregation `fixed`	(`SUM`ǀ`AVG`ǀ`MAX`)	Aggregation method when requesting other resolutions than interval
precision `fixed`	`integer`	Number of decimal places
description `fixed`	`string`	Description
unit `fixed`	`string`	Unit

Measurements

Request

curl 'https://api.meteocontrol.de/v2/systems/ABCDE/trackers/30001/abbreviations/ELEVATION/measurements?from=2016-11-27T09:00:00+01:00&to=2016-11-27T10:00:00+01:00'

<?php
    $measurementsCriteria = (new MeasurementsCriteria())
        ->withDateFrom(DateTime::createFromFormat(DATE_ATOM, '2016-11-27T09:00:00+01:00'))
        ->withDateTo(DateTime::createFromFormat(DATE_ATOM, '2016-11-27T10:00:00+01:00'));
    /** @var DevicesMeasurement $measurements */
    $measurements = $api->system('ABCDE')->tracker('30001')->abbreviation('ELEVATION')->measurements()
        ->get($measurementsCriteria);

Response

{
  "data": {
    "30001": {
      "ELEVATION": [
        {
          "timestamp": "2016-11-27T09:10:00+01:00",
          "value": 180.6
        }
      ]
    }
  }
}

<?php
    /** @var DevicesMeasurement $measurements */
    echo $measurements['30001']['ELEVATION'][0]
        ->timestamp->format(DATE_ATOM);// 2016-11-27T09:10:00+01:00
    echo $measurements['30001']['ELEVATION'][0]->value;// 180.6

GET systems/<systemKey>/trackers/<deviceId>/abbreviations/<abbreviationId>/measurements

Path parameters

Name	Type	Description
systemKey `required`	`string`	Identification key of the system
deviceId `required`	`string`	Can contain up to 10 comma delimited tracker device IDs
abbreviationId `required`	`string`	Can contain up to 5 comma delimited abbreviation IDs

Query parameters

Name	Type	Description
from `required`¹	`date`ǀ`datetime`	Start date
to `required`¹	`date`ǀ`datetime`	End date
resolution `optional`	(`minute²`ǀ`interval`ǀ`fifteen-minutes`ǀ`thirty-minutes`ǀ`hour`ǀ`day`ǀ`month`ǀ`year`)	Defaults to `interval`
includeInterval `optional`³	`integer` `0`ǀ`1`	Defaults to `0`

¹ The maximum time span between from and to varies depending on the resolution as listed below.

Resolution	Maximum time span
minute	1 day
interval	31 days
fifteen-minutes	31 days
thirty-minutes	31 days
hour	31 days
day	60 days
month	1 year
year	no limitation

² The option minute resolution is only supported by meteocontrol blue'Log XM / XC (Firmware 2.0 and higher)
³ Only for interval resolution

Response

Property	Type	Description
timestamp `fixed`	`datetime`	Timestamp
value `fixed`	`number`	Value

Bulk

Request

curl 'https://api.meteocontrol.de/v2/systems/ABCDE/trackers/bulk/measurements?from=2016-11-27T09:00:00+01:00&to=2016-11-27T10:00:00+01:00'

<?php
    $measurementsCriteria = (new MeasurementsCriteria())
        ->withDateFrom(DateTime::createFromFormat(DATE_ATOM, '2016-11-27T09:00:00+01:00'))
        ->withDateTo(DateTime::createFromFormat(DATE_ATOM, '2016-11-27T10:00:00+01:00'));
    $bulkData = $api->system('ABCDE')->trackers()->bulk()->measurements()
        ->get($measurementsCriteria);

Response

{
  "2016-11-27T09:10:00+01:00": {
    "30001": {
      "ELEVATION": 180.6,
      "ELEVATION_TARGET": 192,
      "QS_CI": 100,
      "QS_RX": 40,
      "QS_TX": 40,
      "STATE1": 0
    },
    "30002": {
      "ELEVATION": 180.6,
      "ELEVATION_TARGET": 192,
      "QS_CI": 100,
      "QS_RX": 40,
      "QS_TX": 40,
      "STATE1": 0
    }
  }
}

<?php
    /** @var array $bulkDataArray */
    $bulkDataArray = $bulkData->getAsArray();
    echo $bulkDataArray['2016-11-27T09:10:00+01:00']['30001']['ELEVATION'];// 180.6
    echo $bulkDataArray['2016-11-27T09:10:00+01:00']['30001']['ELEVATION_TARGET'];// 192
    echo $bulkDataArray['2016-11-27T09:10:00+01:00']['30001']['QS_CI'];// 100
    echo $bulkDataArray['2016-11-27T09:10:00+01:00']['30001']['QS_RX'];// 40
    echo $bulkDataArray['2016-11-27T09:10:00+01:00']['30001']['QS_TX'];// 40
    echo $bulkDataArray['2016-11-27T09:10:00+01:00']['30001']['STATE1'];// 0
    echo $bulkDataArray['2016-11-27T09:10:00+01:00']['30002']['ELEVATION'];// 180.6
    echo $bulkDataArray['2016-11-27T09:10:00+01:00']['30002']['ELEVATION_TARGET'];// 192
    echo $bulkDataArray['2016-11-27T09:10:00+01:00']['30002']['QS_CI'];// 100
    echo $bulkDataArray['2016-11-27T09:10:00+01:00']['30002']['QS_RX'];// 40
    echo $bulkDataArray['2016-11-27T09:10:00+01:00']['30002']['QS_TX'];// 40
    echo $bulkDataArray['2016-11-27T09:10:00+01:00']['30002']['STATE1'];// 0

GET systems/<systemKey>/trackers/bulk/measurements

Path parameters

Name	Type	Description
systemKey `required`	`string`	Identification key of the system

Query parameters

Name	Type	Description
from `required`¹	`date`ǀ`datetime`	Start date
to `required`¹	`date`ǀ`datetime`	End date
format `optional`	`json`ǀ`csv`	Export format, defaults to `json`
resolution `optional`	(`minute²`ǀ`interval`ǀ`fifteen-minutes`ǀ`thirty-minutes`ǀ`hour`ǀ`day`)	Defaults to `interval`
deviceIds `optional`	`string`	Comma separated deviceIds
abbreviations `optional`	`string`	Comma separated abbreviations
includeInterval `optional`³	`integer` `0`ǀ`1`	Defaults to `0`

Options for CSV format

The following query parameters are valid only if format is csv
For response example in CSV format, please check HERE.

Name	Type	Description
delimiter	`comma`ǀ`semicolon`ǀ`colon`ǀ`tab`	The delimiter, defaults to `comma`
lineBreak	`LF`ǀ`CR`ǀ`CR/LF`	The line breaks, defaults to `LF`
decimalPoint	`dot`ǀ`comma`	The decimal point, defaults to `dot`
emptyPlaceholder	`text`, empty string by default, any text accepted	The place holder for empty value
precision	`integer`, accepts from 0 to 4	The decimal precision, defaults to `2`

KPI targets

Target PR

Get monthly target PR values (%)

Request

curl 'https://api.meteocontrol.de/v2/systems/ABCDE/kpi-targets/pr'

<?php
    /** @var float[] $targetPrValues */
    $targetPrValues = $api->system('ABCDE')->kpiTargets()->pr()->get();

Response

<?php
    /** @var float[] $targetPrValues */
    echo $targetPrValues[0];// 85
    echo $targetPrValues[1];// 85.3

GET systems/<systemKey>/kpi-targets/pr

Path parameters

Name	Type	Description
systemKey `required`	`string`	Identification key of the system

Response

Status code	Description
`200`	Returns a list of monthly target PR values
`403`	The user is not allowed to get the target PR

Update monthly target PR values (%)

Request

curl -i -X PUT \
   -H 'Content-Type:application/json' \
   -d '[85, 85.3, 86, 86.2, 87.2, 87.5, 90, 91, 84, 83.9, 83, 84]' \
'https://api.meteocontrol.de/v2/systems/ABCDE/kpi-targets/pr'

<?php
    $targetPrValues = [85, 85.3, 86, 86.2, 87.2, 87.5, 90, 91, 84, 83.9, 83, 84];
    $api->system('ABCDE')->kpiTargets()->pr()->set($targetPrValues);

Response

PUT systems/<systemKey>/kpi-targets/pr

Path parameters

Name	Type	Description
systemKey `required`	`string`	Identification key of the system

Request headers

Name	Type	Description
Content-Type `required`	`application/json`

Request body (JSON)

An array of 12 number elements, whose values are between 0.0 and 100.0

Response

Status code	Description
`204`	The target PR has been successfully updated
`400`	The input target PR values are not valid
`403`	The user is not allowed to update the target PR

Delete monthly target PR values (%)

The default target PR values will be used after custom values are successfully deleted.

Request

curl -i -X DELETE 'https://api.meteocontrol.de/v2/systems/ABCDE/kpi-targets/pr'

<?php
    $api->system('ABCDE')->kpiTargets()->pr()->delete();

Response

DELETE systems/<systemKey>/kpi-targets/pr

Path parameters

Name	Type	Description
systemKey `required`	`string`	Identification key of the system

Response

Status code	Description
`204`	The target PR has been successfully deleted
`403`	The user is not allowed to delete the target PR

Target availability

Get monthly target availability values (%)

Request

curl 'https://api.meteocontrol.de/v2/systems/ABCDE/kpi-targets/availability'

<?php
    /** @var float[] $targetAvailabilityValues */
    $targetAvailabilityValues = $api->system('ABCDE')->kpiTargets()->availability()->get();

Response

{
  "data": [
    99,
    99.4,
    99.1,
    99.6,
    99,
    99,
    99,
    99,
    99,
    99,
    99.3,
    99.4
  ]
}

<?php
    /** @var float[] $targetAvailabilityValues */
    echo $targetAvailabilityValues[0];// 99
    echo $targetAvailabilityValues[1];// 99.4

GET systems/<systemKey>/kpi-targets/availability

Path parameters

Name	Type	Description
systemKey `required`	`string`	Identification key of the system

Response

Status code	Description
`200`	Returns a list of monthly target availability values
`403`	The user is not allowed to get the target availability

Update monthly target availability values (%)

Request

curl -i -X PUT \
   -H 'Content-Type:application/json' \
   -d '[85, 85.1, 85.3, 85.5, 90.4, 90.2, 90, 91, 93.4, 95, 95.7, 95.8]' \
'https://api.meteocontrol.de/v2/systems/ABCDE/kpi-targets/availability'

<?php
    $targetAvailabilityValues = [85, 85.1, 85.3, 85.5, 90.4, 90.2, 90, 91, 93.4, 95, 95.7, 95.8];
    $api->system('ABCDE')->kpiTargets()->availability()->set($targetAvailabilityValues);

Response

PUT systems/<systemKey>/kpi-targets/availability

Path parameters

Name	Type	Description
systemKey `required`	`string`	Identification key of the system

Request headers

Name	Type	Description
Content-Type `required`	`application/json`

Request body (JSON)

An array of 12 number elements, whose values are between 0.0 and 100.0

Response

Status code	Description
`204`	The target availability has been successfully updated
`400`	The input target availability values are not valid
`403`	The user is not allowed to update the target availability

Delete monthly target availability values (%)

The default target availability values will be used after custom values are successfully deleted.

Request

curl -i -X DELETE 'https://api.meteocontrol.de/v2/systems/ABCDE/kpi-targets/availability'

<?php
    $api->system('ABCDE')->kpiTargets()->availability()->delete();

Response

DELETE systems/<systemKey>/kpi-targets/availability

Path parameters

Name	Type	Description
systemKey `required`	`string`	Identification key of the system

Response

Status code	Description
`204`	The target availability has been successfully deleted
`403`	The user is not allowed to delete the target availability

Responsibilities

Get information of responsibilities

Request

curl 'https://api.meteocontrol.de/v2/systems/ABCDE/responsibilities'

<?php
    /** @var Responsibilities $responsibilities */
    $responsibilities = $api->system('ABCDE')->responsibilities()->get();

Response

{
  "data": {
    "alarmContact": {
      "address": {
        "city": "City",
        "country": "Country",
        "postalCode": "12345",
        "street": "Street 123",
        "streetAddition": "2F-1"
      },
      "cellphone": "0987654321",
      "company": "Company",
      "email": "example@example.com",
      "fax": "0234567890",
      "firstName": "First Name",
      "id": "123",
      "language": "en",
      "lastName": "Last Name",
      "telephone": "0234567891",
      "timezone": {
        "name": "Europe/Berlin",
        "utcOffset": "+02:00"
      },
      "hasVcom": true,
      "title": "Mr.",
      "username": "user.name"
    },
    "electrician": {
      "address": {
        "city": "City",
        "country": "Country",
        "postalCode": "12345",
        "street": "Street 123",
        "streetAddition": "2F-1"
      },
      "cellphone": "0987654321",
      "company": "Company",
      "email": "example@example.com",
      "fax": "0234567890",
      "firstName": "First Name",
      "id": "123",
      "language": "en",
      "lastName": "Last Name",
      "telephone": "0234567891",
      "timezone": {
        "name": "Europe/Berlin",
        "utcOffset": "+02:00"
      },
      "hasVcom": true,
      "title": "Mr.",
      "username": "user.name"
    },
    "invoiceRecipient": {
      "address": {
        "city": "City",
        "country": "Country",
        "postalCode": "12345",
        "street": "Street 123",
        "streetAddition": "2F-1"
      },
      "cellphone": "0987654321",
      "company": "Company",
      "email": "example@example.com",
      "fax": "0234567890",
      "firstName": "First Name",
      "id": "123",
      "language": "en",
      "lastName": "Last Name",
      "telephone": "0234567891",
      "timezone": {
        "name": "Europe/Berlin",
        "utcOffset": "+02:00"
      },
      "hasVcom": true,
      "title": "Mr.",
      "username": "user.name"
    },
    "operator": {
      "address": {
        "city": "City",
        "country": "Country",
        "postalCode": "12345",
        "street": "Street 123",
        "streetAddition": "2F-1"
      },
      "cellphone": "0987654321",
      "company": "Company",
      "email": "example@example.com",
      "fax": "0234567890",
      "firstName": "First Name",
      "id": "123",
      "language": "en",
      "lastName": "Last Name",
      "telephone": "0234567891",
      "timezone": {
        "name": "Europe/Berlin",
        "utcOffset": "+02:00"
      },
      "hasVcom": true,
      "title": "Mr.",
      "username": "user.name"
    },
    "owner": {
      "address": {
        "city": "City",
        "country": "Country",
        "postalCode": "12345",
        "street": "Street 123",
        "streetAddition": "2F-1"
      },
      "cellphone": "0987654321",
      "company": "Company",
      "email": "example@example.com",
      "fax": "0234567890",
      "firstName": "First Name",
      "id": "123",
      "language": "en",
      "lastName": "Last Name",
      "telephone": "0234567891",
      "timezone": {
        "name": "Europe/Berlin",
        "utcOffset": "+02:00"
      },
      "hasVcom": true,
      "title": "Mr.",
      "username": "user.name"
    }
  }
}

<?php
    /** @var Responsibilities $responsibilities */
    echo $responsibilities->owner->address->city; // 'City'
    echo $responsibilities->owner->address->country; // 'Country'
    echo $responsibilities->owner->address->postalCode; // '12345'
    echo $responsibilities->owner->address->street; // 'Street 123'
    echo $responsibilities->owner->address->streetAddition; // '2F-1'
    echo $responsibilities->owner->timezone->name; // 'Europe/Berlin'
    echo $responsibilities->owner->timezone->utcOffset; // '+02:00'
    echo $responsibilities->owner->id; // "123"
    echo $responsibilities->owner->title; // 'Mr.'
    echo $responsibilities->owner->firstName; // 'First Name'
    echo $responsibilities->owner->lastName; // 'Last Name'
    echo $responsibilities->owner->username; // 'user.name'
    echo $responsibilities->owner->email; // 'example@example.com'
    echo $responsibilities->owner->language; // 'en'
    echo $responsibilities->owner->company; // 'Company'
    echo $responsibilities->owner->fax; // '0234567890'
    echo $responsibilities->owner->telephone; // '0234567891'
    echo $responsibilities->owner->cellphone; // '0987654321'
    echo $responsibilities->owner->hasVcom; // true

    echo $responsibilities->operator->address->city; // 'City'
    echo $responsibilities->operator->address->country; // 'Country'
    echo $responsibilities->operator->address->postalCode; // '12345'
    echo $responsibilities->operator->address->street; // 'Street 123'
    echo $responsibilities->operator->address->streetAddition; // '2F-1'
    echo $responsibilities->operator->timezone->name; // 'Europe/Berlin'
    echo $responsibilities->operator->timezone->utcOffset; // '+02:00'
    echo $responsibilities->operator->id; // "123"
    echo $responsibilities->operator->title; // 'Mr.'
    echo $responsibilities->operator->firstName; // 'First Name'
    echo $responsibilities->operator->lastName; // 'Last Name'
    echo $responsibilities->operator->username; // 'user.name'
    echo $responsibilities->operator->email; // 'example@example.com'
    echo $responsibilities->operator->language; // 'en'
    echo $responsibilities->operator->company; // 'Company'
    echo $responsibilities->operator->fax; // '0234567890'
    echo $responsibilities->operator->telephone; // '0234567891'
    echo $responsibilities->operator->cellphone; // '0987654321'
    echo $responsibilities->operator->hasVcom; // true

    echo $responsibilities->electrician->address->city; // 'City'
    echo $responsibilities->electrician->address->country; // 'Country'
    echo $responsibilities->electrician->address->postalCode; // '12345'
    echo $responsibilities->electrician->address->street; // 'Street 123'
    echo $responsibilities->electrician->address->streetAddition; // '2F-1'
    echo $responsibilities->electrician->timezone->name; // 'Europe/Berlin'
    echo $responsibilities->electrician->timezone->utcOffset; // '+02:00'
    echo $responsibilities->electrician->id; // "123"
    echo $responsibilities->electrician->title; // 'Mr.'
    echo $responsibilities->electrician->firstName; // 'First Name'
    echo $responsibilities->electrician->lastName; // 'Last Name'
    echo $responsibilities->electrician->username; // 'user.name'
    echo $responsibilities->electrician->email; // 'example@example.com'
    echo $responsibilities->electrician->language; // 'en'
    echo $responsibilities->electrician->company; // 'Company'
    echo $responsibilities->electrician->fax; // '0234567890'
    echo $responsibilities->electrician->telephone; // '0234567891'
    echo $responsibilities->electrician->cellphone; // '0987654321'
    echo $responsibilities->electrician->hasVcom; // true

    echo $responsibilities->invoiceRecipient->address->city; // 'City'
    echo $responsibilities->invoiceRecipient->address->country; // 'Country'
    echo $responsibilities->invoiceRecipient->address->postalCode; // '12345'
    echo $responsibilities->invoiceRecipient->address->street; // 'Street 123'
    echo $responsibilities->invoiceRecipient->address->streetAddition; // '2F-1'
    echo $responsibilities->invoiceRecipient->timezone->name; // 'Europe/Berlin'
    echo $responsibilities->invoiceRecipient->timezone->utcOffset; // '+02:00'
    echo $responsibilities->invoiceRecipient->id; // "123"
    echo $responsibilities->invoiceRecipient->title; // 'Mr.'
    echo $responsibilities->invoiceRecipient->firstName; // 'First Name'
    echo $responsibilities->invoiceRecipient->lastName; // 'Last Name'
    echo $responsibilities->invoiceRecipient->username; // 'user.name'
    echo $responsibilities->invoiceRecipient->email; // 'example@example.com'
    echo $responsibilities->invoiceRecipient->language; // 'en'
    echo $responsibilities->invoiceRecipient->company; // 'Company'
    echo $responsibilities->invoiceRecipient->fax; // '0234567890'
    echo $responsibilities->invoiceRecipient->telephone; // '0234567891'
    echo $responsibilities->invoiceRecipient->cellphone; // '0987654321'
    echo $responsibilities->invoiceRecipient->hasVcom; // true

    echo $responsibilities->alarmContact->address->city; // 'City'
    echo $responsibilities->alarmContact->address->country; // 'Country'
    echo $responsibilities->alarmContact->address->postalCode; // '12345'
    echo $responsibilities->alarmContact->address->street; // 'Street 123'
    echo $responsibilities->alarmContact->address->streetAddition; // '2F-1'
    echo $responsibilities->alarmContact->timezone->name; // 'Europe/Berlin'
    echo $responsibilities->alarmContact->timezone->utcOffset; // '+02:00'
    echo $responsibilities->alarmContact->id; // "123"
    echo $responsibilities->alarmContact->title; // 'Mr.'
    echo $responsibilities->alarmContact->firstName; // 'First Name'
    echo $responsibilities->alarmContact->lastName; // 'Last Name'
    echo $responsibilities->alarmContact->username; // 'user.name'
    echo $responsibilities->alarmContact->email; // 'example@example.com'
    echo $responsibilities->alarmContact->language; // 'en'
    echo $responsibilities->alarmContact->company; // 'Company'
    echo $responsibilities->alarmContact->fax; // '0234567890'
    echo $responsibilities->alarmContact->telephone; // '0234567891'
    echo $responsibilities->alarmContact->cellphone; // '0987654321'
    echo $responsibilities->alarmContact->hasVcom; // true

GET systems/<systemKey>/responsibilities

Path parameters

Name	Type	Description
systemKey `required`	`string`	Identification key of the system

Users

Get user list

Request

curl 'https://api.meteocontrol.de/v2/systems/ABCDE/users'

<?php
    /** @var User[] $users */
    $users = $api->system('ABCDE')->users()->get();

Response

{
  "data": [
    {
      "id": "123",
      "username": "user1.name",
      "firstName": "First Name",
      "lastName": "Last Name"
    },
    {
      "id": "456",
      "username": "user2.name",
      "firstName": "First Name",
      "lastName": "Last Name"
    }
  ]
}

<?php
    /** @var User[] $users */
    echo $users[0]->id;// "123"
    echo $users[0]->username;// "user1.name"
    echo $users[0]->firstName;// "First Name"
    echo $users[0]->lastName;// "Last Name"

GET systems/<systemKey>/users

Path parameters

Name	Type	Description
systemKey `required`	`string`	Identification key of the system

Response

Property	Type	Description
id `fixed`	`string`	User ID
username `fixed`	`string`	Username
firstName `fixed`	`string`	First name
lastName `fixed`	`string`	Last name

Get single user information by its ID

Request

curl 'https://api.meteocontrol.de/v2/systems/ABCDE/users/123'

<?php
    /** @var UserDetail $userDetail */
    $userDetail = $api->system('ABCDE')->user(123)->get();

Response

{
  "data": {
    "id": "123",
    "title": "Mrs.",
    "firstName": "First Name",
    "lastName": "Last Name",
    "username": "user1.name",
    "email": "example@example.com",
    "language": "en",
    "company": "Company",
    "fax": "0234567890",
    "telephone": "0234567891",
    "cellphone": "0987654321",
    "address": {
      "city": "City",
      "country": "Country",
      "postalCode": "12345",
      "street": "Street 123",
      "streetAddition": "2F-1"
    },
    "timezone": {
      "name": "Europe/Berlin",
      "utcOffset": "+02:00"
    },
    "hasVcom": true
  }
}

<?php
    /** @var UserDetail $userDetail */
    echo $userDetail->id;//"123"
    echo $userDetail->title;//"Mrs."
    echo $userDetail->firstName;//"First Name"
    echo $userDetail->lastName;//"Last Name"
    echo $userDetail->username;//"user1.name"
    echo $userDetail->email;//"example@example.com"
    echo $userDetail->language;//"en"
    echo $userDetail->company;//"Company"
    echo $userDetail->fax;//"0234567890"
    echo $userDetail->telephone;//"0234567891"
    echo $userDetail->cellphone;//"0987654321"
    echo $userDetail->address->city;//"City"
    echo $userDetail->address->country;//"Country"
    echo $userDetail->address->street;//"Street 123"
    echo $userDetail->address->streetAddition;//"2F-1"
    echo $userDetail->address->postalCode;//"12345"
    echo $userDetail->timezone->name;//"Europe/Berlin"
    echo $userDetail->timezone->utcOffset;//"+02:00"
    echo $userDetail->hasVcom;//true

GET systems/<systemKey>/users/<userId>

Path parameters

Name	Type	Description
systemKey `required`	`string`	Identification key of the system
userId `required`	`integer`	User ID

Get single user information by its username

Request

curl 'https://api.meteocontrol.de/v2/systems/ABCDE/users?username=user1.name'

<?php
    $criteria = (new UserCriteria())
        ->withUsername('user1.name');
    /** @var UserDetail $user */
    $user = $api->system('ABCDE')->users()->get($criteria);

Response

{
  "data": {
    "id": "123",
    "title": "Mrs.",
    "firstName": "First Name",
    "lastName": "Last Name",
    "username": "user1.name",
    "email": "example@example.com",
    "language": "en",
    "company": "Company",
    "fax": "0234567890",
    "telephone": "0234567891",
    "cellphone": "0987654321",
    "address": {
      "city": "City",
      "country": "Country",
      "postalCode": "12345",
      "street": "Street 123",
      "streetAddition": "2F-1"
    },
    "timezone": {
      "name": "Europe/Berlin",
      "utcOffset": "+02:00"
    },
    "hasVcom": true
  }
}

<?php
    /** @var UserDetail $userDetail */
    echo $userDetail->id;//"123"
    echo $userDetail->title;//"Mrs."
    echo $userDetail->firstName;//"First Name"
    echo $userDetail->lastName;//"Last Name"
    echo $userDetail->username;//"user1.name"
    echo $userDetail->email;//"example@example.com"
    echo $userDetail->language;//"en"
    echo $userDetail->company;//"Company"
    echo $userDetail->fax;//"0234567890"
    echo $userDetail->telephone;//"0234567891"
    echo $userDetail->cellphone;//"0987654321"
    echo $userDetail->address->city;//"City"
    echo $userDetail->address->country;//"Country"
    echo $userDetail->address->street;//"Street 123"
    echo $userDetail->address->streetAddition;//"2F-1"
    echo $userDetail->address->postalCode;//"12345"
    echo $userDetail->timezone->name;//"Europe/Berlin"
    echo $userDetail->timezone->utcOffset;//"+02:00"
    echo $userDetail->hasVcom;//true

GET systems/<systemKey>/users

Path parameters

Name	Type	Description
systemKey `required`	`string`	Identification key of the system

Query parameters

Name	Type	Description
username `required`	`string`	User name

Pictures

Get system picture

Request

curl 'https://api.meteocontrol.de/v2/systems/ABCDE/picture'

<?php
    /** @var PictureFile $pictureFile */
    $pictureFile = $api->system('ABCDE')->picture()->get();

Response

{
  "data":{
    "id": 12345,
    "filename": "12345.jpg",
    "content": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD.....",
    "type": "image/jpeg"
  }
}

<?php
    /** @var PictureFile $pictureFile */
    echo $pictureFile->id;// 12345
    echo $pictureFile->filename;// 12345.jpg
    echo $pictureFile->content;// "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD....."
    echo $pictureFile->type;// "image/jpeg"

GET systems/<systemKey>/picture

Path parameters

Name	Type	Description
systemKey `required`	`string`	Identification key of the system

Response

PictureFile object

Property	Type	Description
id `fixed`	`integer`	Picture ID
filename `fixed`	`string`	File name
content `fixed`	`string`	Data URI (RFC2397) with base64 encoding.
type `fixed`	`string`	image type

Tickets

Get all tickets

Request

curl 'https://api.meteocontrol.de/v2/tickets?
includeInReports=no&severity=normal&priority=normal&status=open&assignee=username&systemKey=ABCDE
&lastChangedAt[from]=2016-01-01T00:00:00+02:00&lastChangedAt[to]=2016-01-31T00:00:00+02:00
&createdAt[from]=2016-04-01T00:00:00+02:00&createdAt[to]=2016-04-25T00:00:00+02:00
&rectifiedAt[from]=2016-04-25T00:00:00+02:00&rectifiedAt[to]=2016-04-25T00:00:00+02:00'

<?php
    $ticketsCriteria = (new TicketsCriteria())
        ->withSystemKey('ABCDE')
        ->withStatus(Ticket::STATUS_OPEN)
        ->withAssignee('username')
        ->withPriority(Ticket::PRIORITY_NORMAL)
        ->withSeverity(Ticket::SEVERITY_NORMAL)
        ->withIncludeInReports(Ticket::REPORT_TYPE_NO)
        ->withLastChangedAtFrom(DateTime::createFromFormat(DATE_ATOM, '2016-01-01T00:00:00+02:00'))
        ->withLastChangedAtTo(DateTime::createFromFormat(DATE_ATOM, '2016-01-31T00:00:00+02:00'))
        ->withCreatedAtFrom(DateTime::createFromFormat(DATE_ATOM, '2016-04-01T00:00:00+02:00'))
        ->withCreatedAtTo(DateTime::createFromFormat(DATE_ATOM, '2016-04-25T00:00:00+02:00'))
        ->withRectifiedAtFrom(DateTime::createFromFormat(DATE_ATOM, '2016-04-25T00:00:00+02:00'))
        ->withRectifiedAtTo(DateTime::createFromFormat(DATE_ATOM, '2016-04-25T00:00:00+02:00'));
    /** @var Ticket[] $tickets */
    $tickets = $api->tickets()->find($ticketsCriteria);

Response

{
  "data": [
    {
      "id": "123",
      "systemKey": "ABCDE",
      "designation": "Ticket #123",
      "description": "This is a description",
      "summary": "This is a summary.",
      "createdAt": "2016-01-01T12:00:00+02:00",
      "lastChangedAt": "2016-01-01T13:00:00+02:00",
      "rectifiedAt": "2016-01-01T13:00:00+02:00",
      "status": "closed",
      "priority": "normal",
      "fieldService": "true",
      "severity": "normal"
    },
    {
      "id": "456",
      "systemKey": "FGHIJ",
      "designation": "Ticket #456",
      "description": "This is a description",
      "summary": "This is a summary.",
      "createdAt": "2016-02-01T12:00:00+02:00",
      "lastChangedAt": "2016-02-02T13:00:00+02:00",
      "rectifiedAt": "2016-02-02T13:00:00+02:00",
      "status": "inProgress",
      "priority": "high",
      "fieldService": "false",
      "severity": null
    }
  ]
}

<?php
    echo $tickets[0]->id;// 123
    echo $tickets[0]->systemKey;// ABCDE
    echo $tickets[0]->designation;// Ticket #123
    echo $tickets[0]->description;// This is a description
    echo $tickets[0]->summary;// This is a summary.
    echo $tickets[0]->createdAt->format(DATE_ATOM);// 2016-01-01T12:00:00+02:00
    echo $tickets[0]->lastChangedAt->format(DATE_ATOM);// 2016-01-01T13:00:00+02:00
    echo $tickets[0]->rectifiedAt->format(DATE_ATOM);// 2016-01-01T13:00:00+02:00
    echo $tickets[0]->status;// closed
    echo $tickets[0]->priority;// normal
    echo $tickets[0]->fieldService;// true
    echo $tickets[0]->severity;// normal
    echo $tickets[1]->id;// 456
    echo $tickets[1]->systemKey;// FGHIJ
    echo $tickets[1]->designation;// Ticket #456
    echo $tickets[1]->summary;// This is a summary.
    echo $tickets[1]->createdAt->format(DATE_ATOM);// 2016-02-01T12:00:00+02:00
    echo $tickets[1]->lastChangedAt->format(DATE_ATOM);// 2016-02-02T13:00:00+02:00
    echo $tickets[1]->rectifiedAt->format(DATE_ATOM);// 2016-02-02T13:00:00+02:00
    echo $tickets[1]->status;// inProgress
    echo $tickets[1]->priority;// high
    echo $tickets[1]->fieldService;// false
    echo $tickets[1]->severity;// null

GET tickets

Query parameters

Name	Type	Description
lastChangedAt[from] `optional`	`datetime`	Start date
lastChangedAt[to] `optional`	`datetime`	End date
createdAt[from] `optional`	`datetime`	Start date
createdAt[to] `optional`	`datetime`	End date
rectifiedAt[from] `optional`	`datetime`	Start date
rectifiedAt[to] `optional`	`datetime`	End date
includeInReports `optional`	(`no`ǀ`detail`ǀ`summary`)	Can contain comma delimited report types
status `optional`	(`open`ǀ`closed`ǀ`deleted`ǀ`assigned`ǀ`inProgress`)¹	Can contain comma delimited status
severity `optional`	(`normal`ǀ`high`ǀ`critical`)	Can contain comma delimited severity types
priority `optional`	(`low`ǀ`normal`ǀ`high`ǀ`urgent`)	Can contain comma delimited priority types
assignee `optional`	`string`	The username of the person being assigned to the ticket, it can contain comma delimited names
systemKey `optional`		can contain comma delimited system keys

¹ Customized statuses available. Please reach out to our sales representatives for more information.

Response

Ticket object

Property	Type	Description
id `fixed`	`string`
systemKey `fixed`	`string`	Identification key of the system
designation `fixed`	`string`
description `fixed`	`string`
summary `fixed`	`string`ǀ`null`
createdAt `fixed`	`datetime`	Created date in system timezone
lastChangedAt `fixed`	`datetime`ǀ`null`	Last change date in system timezone
rectifiedAt `fixed`	`datetime`ǀ`null`	Rectified date in system timezone
status `fixed`	(`open`ǀ`closed`ǀ`deleted`ǀ`assigned`ǀ`inProgress`)¹
priority `fixed`	(`low`ǀ`normal`ǀ`high`ǀ`urgent`ǀ`null`)
fieldService `fixed`	`bool`
severity `fixed`	(`normal`ǀ`high`ǀ`critical`ǀ`null`)

¹ Customized statuses available. Please reach out to our sales representatives for more information.

Get ticket causes

Returns a list of all available causes for ticket.

Request

curl 'https://api.meteocontrol.de/v2/tickets/causes'

<?php
    /** @var string[] causes */
    $causes = $api->tickets()->causes()->get();

Response

{
  "data":[
    "Unknown",
    "Grid voltage",
    "Inverter",
    "Operating error",
    "Overvoltage arrester"
  ]
}

<?php
    /** @var string[] causes */
    echo $causes[0];// Unknown
    echo $causes[1];// Grid voltage
    echo $causes[2];// Inverter
    echo $causes[3];// Operating error
    echo $causes[4];// Overvoltage arrester

Get single ticket

Request

curl 'https://api.meteocontrol.de/v2/tickets/123'

<?php
    /** @var Ticket $ticket */
    $ticket = $api->ticket(123)->get();

Response

{
  "data": {
    "id": "123",
    "systemKey": "ABCDE",
    "designation": "Ticket #123",
    "description": "This is a description",
    "summary": "This is a summary.",
    "createdAt": "2016-01-01T12:00:00+02:00",
    "lastChangedAt": "2016-01-01T13:00:00+02:00",
    "rectifiedAt": "2016-01-01T14:00:00+02:00",
    "assignee": null,
    "status": "inProgress",
    "causeId": 10,
    "cause": "Inverter",
    "priority": "normal",
    "includeInReports": "no",
    "fieldService": true,
    "severity": "normal",
    "outage": null
  }
}

<?php
    /** @var Ticket $ticket */
    echo $ticket->id;// 123
    echo $ticket->systemKey;// ABCDE
    echo $ticket->designation;// Ticket #123
    echo $ticket->description;// This is a description
    echo $ticket->summary;// This is a summary.
    echo $ticket->createdAt->format(DATE_ATOM);// 2016-01-01T12:00:00+02:00
    echo $ticket->lastChangedAt->format(DATE_ATOM);// 2016-01-01T13:00:00+02:00
    echo $ticket->rectifiedAt->format(DATE_ATOM);// 2016-01-01T14:00:00+02:00
    echo $ticket->assignee;// null
    echo $ticket->status;// inProgress
    echo $ticket->causeId;// 10
    echo $ticket->cause;// Inverter
    echo $ticket->priority;// normal
    echo $ticket->includeInReports;// no
    echo $ticket->fieldService;// true
    echo $ticket->severity;// normal
    echo $ticket->outage;// null

¹ Customized statuses available. Please reach out to our sales representatives for more information.

GET tickets/<ticketId>

Path parameters

Name	Type	Description
ticketId `required`	`integer`	Ticket ID

Response

Ticket object

Property	Type	Description
id `fixed`	`string`
systemKey `fixed`	`string`	Identification key of the system
designation `fixed`	`string`
description `fixed`	`string`
summary `fixed`	`string`ǀ`null`
createdAt `fixed`	`datetime`	Created date in system timezone
lastChangedAt `fixed`	`datetime`ǀ`null`	Last change date in system timezone
rectifiedAt `fixed`	`datetime`ǀ`null`	Rectified date in system timezone
assignee `fixed`	`string`ǀ`null`	The username of the person being assigned to the ticket
status `fixed`	(`open`ǀ`closed`ǀ`deleted`ǀ`assigned`ǀ`inProgress`)¹
causeId `fixed`	`integer`ǀ`null`	(deprecated)
cause `fixed`	`string`
priority `fixed`	(`low`ǀ`normal`ǀ`high`ǀ`urgent`ǀ`null`)
includeInReports `fixed`	(`no`ǀ`detail`ǀ`summary`)
fieldService `fixed`	`bool`
severity `fixed`	(`normal`ǀ`high`ǀ`critical`ǀ`null`)
outage `fixed`	`Outage` ǀ `null`	Outage information, if available

¹ Customized statuses available. Please reach out to our sales representatives for more information.

Outage object

Property	Type	Description
startedAt `fixed`	`datetime`	Start of outage
endedAt `fixed`	`datetime` ǀ `null`	End of outage or `null` if undefined
affectedPower `fixed`	`number`	Affected power in kW
shouldInfluenceAvailability `fixed`	`bool`	`true` if outage should affect availability
shouldInfluencePr `fixed`	`bool`	`true` if outage should affect performance ratio

Update a ticket

Request

curl -i -X PATCH \
   -H "Content-Type:application/json" \
   -d \
'{
  "rectifiedAt": "2016-01-01T00:00:00+02:00",
  "status": "closed",
  "includeInReports": "detail",
  "priority": "urgent",
  "description": "description",
  "summary": "summary",
  "assignee": "username"
}' \
 'https://api.meteocontrol.de/v2/tickets/123'

<?php
    /** @var Ticket $ticket */
    $ticket = $api->ticket(123)->get();
    $ticket->rectifiedAt = DateTime::createFromFormat(DATE_ATOM, '2016-01-01T00:00:00+02:00');
    $ticket->status = 'closed';
    $ticket->includeInReports = 'detail';
    $ticket->priority = 'urgent';
    $ticket->description = 'description';
    $ticket->summary = 'summary';
    $api->ticket(123)->update($ticket);

Response

PATCH tickets/<ticketId>

Path parameters

Name	Type	Description
ticketId `required`	`integer`	Ticket ID

Request headers

Name	Type	Description
Content-Type `required`	`application/json`

Request body (JSON)

Property	Type	Description
designation `optional`	`string`
description `optional`	`string`
summary `optional`	`string`ǀ`null`
rectifiedAt `optional`	`datetime`
includeInReports `optional`	(`no`ǀ`detail`ǀ`summary`)
status `optional`	(`open`ǀ`closed`ǀ`deleted`ǀ`assigned`ǀ`inProgress`)¹
priority `optional`	(`low`ǀ`normal`ǀ`high`ǀ`urgent`)
assignee `optional`	`string`	The username of the person being assigned to the ticket
cause `optional`	`string`²
fieldService `optional`	`bool`

¹ Customized statuses available. Please reach out to our sales representatives for more information.
² Please refer to Get ticket causes endpoint for available causes.

Response

The response body is empty.

Http-Code: 204

Create a ticket

Request

curl -i -X POST \
   -H "Content-Type:application/json" \
   -d \
'{
  "designation": "New Ticket",
  "systemKey": "ABCDE",
  "createdAt": "2016-05-25T00:00:00+02:00",
  "status": "open",
  "includeInReports": "no",
  "priority": "normal",
  "summary": "still created from the API",
  "description": "description",
  "assignee": "username"
}' \
 'https://api.meteocontrol.de/v2/tickets'

<?php
    $ticket = new Ticket();
    $ticket->systemKey = 'ABCDE';
    $ticket->designation = 'New Ticket';
    $ticket->createdAt = DateTime::createFromFormat(DATE_ATOM, '2016-05-25T00:00:00+02:00');
    $ticket->status = Ticket::STATUS_OPEN;
    $ticket->includeInReports = Ticket::REPORT_TYPE_NO;
    $ticket->priority = Ticket::PRIORITY_NORMAL;
    $ticket->summary = 'still created from the API';
    $ticket->description = 'description';

    /** @var integer $ticketId */
    $ticketId = $api->tickets()->create($ticket);

Response

{
  "data":{
    "ticketId": "123"
  },
  "paths":{
    "GET": "/tickets/123",
    "PATCH": "/tickets/123",
    "DELETE": "/tickets/123"
  }
}

<?php
    /** @var integer $ticketId */
    echo $ticketId;// 123

POST tickets

Request headers

Name	Type	Description
Content-Type `required`	`application/json`

Request body (JSON)

Property	Type	Description
systemKey `required`	`string`	Identification key of the system
designation `required`	`string`
createdAt `required`	`datetime`
description `optional`	`string`
summary `optional`	`string`ǀ`null`
includeInReports `optional`	(`no`ǀ`detail`ǀ`summary`)
status `optional`	(`open`ǀ`closed`ǀ`deleted`ǀ`assigned`ǀ`inProgress`)¹
priority `optional`	(`low`ǀ`normal`ǀ`high`ǀ`urgent`)
assignee `optional`	`string`	The username of the person being assigned to the ticket
cause `optional`	`string`²
fieldService `optional`	`bool`

¹ Customized statuses available. Please reach out to our sales representatives for more information.
² Please refer to Get ticket causes endpoint for available causes.

Response - Data

Property	Type	Description
ticketId `fixed`	`string`	Of the new ticket

Response - Paths

Method	type	Description
get `fixed`	`string`	GET method with URL
patch `fixed`	`string`	PATCH method with URL
delete `fixed`	`string`	DELETE method with URL

Delete a ticket

Request

curl -i -X DELETE 'https://api.meteocontrol.de/v2/tickets/123'

<?php
    $api->ticket(123)->delete();

Response

DELETE tickets/<ticketId>

Path parameters

Name	Type	Description
ticketId `required`	`integer`	Ticket ID

Response

Status code	Description
`204`	If the ticket has no open alarms
`403`	If the ticket has open alarms and therefore cannot be deleted

Comments

Get all comments

Request

curl 'https://api.meteocontrol.de/v2/tickets/123/comments'

<?php
    /** @var Comment[] comments */
    $comments = $api->ticket(123)->comments()->get();

Response

{
  "data":[
    {
      "commentId": 101,
      "createdAt": "2016-02-19T12:49:20+01:00",
      "comment": "Comment text",
      "username": "username",
      "firstName": "firstName",
      "lastName": "lastName"
    },
    {
      "commentId": 102,
      "createdAt": "2016-02-19T12:49:07+01:00",
      "comment": "Comment text",
      "username": "username",
      "firstName": "firstName",
      "lastName": "lastName"
    }
  ]
}

<?php
    /** @var Comment[] comments */
    echo $comments[0]->commentId;// 101
    echo $comments[0]->createdAt->format(DATE_ATOM);// 2016-02-19T12:49:20+01:00
    echo $comments[0]->comment;// Comment text
    echo $comments[0]->username;// username
    echo $comments[0]->firstName;// firstName
    echo $comments[0]->lastName;// lastName
    echo $comments[1]->commentId;// 102
    echo $comments[1]->createdAt->format(DATE_ATOM);// 2016-02-19T12:49:07+01:00
    echo $comments[1]->comment;// Comment text
    echo $comments[1]->username;// username
    echo $comments[1]->firstName;// firstName
    echo $comments[1]->lastName;// lastName

GET tickets/<ticketId>/comments

Path parameters

Name	Type	Description
ticketId `required`	`integer`	Ticket ID

Response

Comment object

Property	Type	Description
commentId `fixed`	`integer`	Comment ID
createdAt `fixed`	`datetime`	Created datetime in system timezone
comment `fixed`	`string`	With new line character `\n`
username `fixed`	`string`	The username of the person who commented

Get single comment

Request

curl 'https://api.meteocontrol.de/v2/tickets/123/comments/101'

<?php
    /** @var CommentDetail comment */
    $comment = $api->ticket(123)->comment(101)->get();

Response

{
  "data":{
    "commentId": 101,
    "createdAt": "2016-02-19T12:49:20+01:00",
    "comment": "Comment text",
    "username": "username",
    "firstName": "firstName",
    "lastName": "lastName"
  }
}

<?php
    /** @var CommentDetail comment */
    echo $comment->commentId;// 101
    echo $comment->createdAt->format(DATE_ATOM);// 2016-02-19T12:49:20+01:00
    echo $comment->comment;// Comment text
    echo $comment->username;// username
    echo $comment->firstName;// firstName
    echo $comment->lastName;// lastName

GET tickets/<ticketId>/comments/<commentId>

Path parameters

Name	Type	Description
ticketId `required`	`integer`	Ticket ID
commentId `required`	`integer`	Comment ID

Response

Comment object

Property	Type	Description
commentId `fixed`	`integer`	Comment ID
createdAt `fixed`	`datetime`	Created datetime in system timezone
comment `fixed`	`string`	With new line character `\n`
username `fixed`	`string`	The username of the person who commented

Create a comment

Request

curl -i -X POST \
   -H "Content-Type:application/json" \
   -d \
'{
  "comment": "New Comment"
}' \
 'https://api.meteocontrol.de/v2/tickets/123/comments'

<?php
    $comment = new CommentDetail();
    $comment->comment = 'New Comment';

    /** @var integer $commentId */
    $commentId = $api->ticket(123)->comments()->create($comment);

Response

{
  "data":{
    "commentId": 103
  }
}

<?php
    /** @var integer $commentId */
    echo $commentId;// 103

POST comments

Path parameters

Name	Type	Description
ticketId `required`	`integer`	Ticket ID
createdAt `optional`	`datetime`

Request headers

Name	Type	Description
Content-Type `required`	`application/json`

Request body (JSON)

Property	Type	Description
comment `required`	`string`

Response

Property	Type	Description
commentId `fixed`	`integer`	Comment ID of the new comment.

Update a comment

Request

curl -i -X PATCH \
   -H "Content-Type:application/json" \
   -d \
'{
  "comment": "New Comment"
}' \
 'https://api.meteocontrol.de/v2/tickets/123/comments/103'

<?php
    $comment = new CommentDetail();
    $comment->comment = 'New Comment';
    $api->ticket(123)->comment(103)->update($comment);

Response

PATCH tickets/<ticketId>/comments/<commentId>

Path parameters

Name	Type	Description
ticketId `required`	`integer`	Ticket ID
commentId `required`	`integer`	Comment ID

Request headers

Name	Type	Description
Content-Type `required`	`application/json`

Request body (JSON)

Property	Type	Description
comment `required`	`string`

Response

The response body is empty.

Http-Code: 204

Delete a comment

Request

curl -i -X DELETE 'https://api.meteocontrol.de/v2/tickets/123/comments/103'

<?php
    $api->ticket(123)->comment(103)->delete();

Response

DELETE tickets/<ticketId>/comments/<commentId>

Path parameters

Name	Type	Description
ticketId `required`	`integer`	Ticket ID
commentId `required`	`integer`	Comment ID

Response

The response body is empty.

Http-Code: 204

Outage

Get single outage

Request

curl 'https://api.meteocontrol.de/v2/tickets/456/outage'

<?php
    /** @var Outage $outage */
    $outage = $api->ticket(456)->outage()->get();

Response

{
  "data": {
    "startedAt": "2016-11-15T10:00:00+01:00",
    "endedAt": "2016-11-15T10:59:59+01:00",
    "affectedPower": 24.03,
    "shouldInfluenceAvailability": false,
    "shouldInfluencePr": false,
    "components": ["Id12345.1", "Id12345.2"]
  }
}

<?php
    /** @var Outage $outage */
    echo $outage->startedAt->format(DATE_ATOM);// 2016-11-15T10:00:00+01:00
    echo $outage->endedAt->format(DATE_ATOM);// 2016-11-15T10:59:59+01:00
    echo $outage->affectedPower;// 24.03
    echo $outage->shouldInfluenceAvailability;// false
    echo $outage->shouldInfluencePr;// false
    echo $outage->components;// ["Id12345.1", "Id12345.2"]

GET tickets/<ticketId>/outage

Path parameters

Name	Type	Description
ticketId `required`	`integer`	Ticket ID

Response

Outage object

Property	Type	Description
startedAt `fixed`	`datetime`	Start of outage
endedAt `fixed`	`datetime`ǀ`null`	End of outage or `null` if undefined
affectedPower `fixed`	`number`	Affected power in kW
shouldInfluenceAvailability `fixed`	`bool`	`true` if outage should affect availability
shouldInfluencePr `fixed`	`bool`	`true` if outage should affect performance ratio
components `fixed`¹	`array`	Component ID `string`

¹ Only inverters accepted for Component ID.

Update an outage

Request

curl -i -X PATCH \
   -H "Content-Type:application/json" \
   -d \
'{
  "startedAt": "2016-11-15T10:00:00+01:00",
  "endedAt": "2016-11-15T10:59:59+01:00",
  "affectedPower": 24.03,
  "shouldInfluenceAvailability": false,
  "shouldInfluencePr": false,
  "components": ["Id12345.1", "Id12345.2"]
}' \
 'https://api.meteocontrol.de/v2/tickets/456/outage'

<?php
    $outage = new Outage();
    $outage->startedAt = new DateTime("2016-11-15T10:00:00+01:00");
    $outage->endedAt = new DateTime("2016-11-15T10:59:59+01:00");
    $outage->affectedPower = 24.03;
    $outage->shouldInfluenceAvailability = false;
    $outage->shouldInfluencePr = false;
    $outage->components = ["Id12345.1", "Id12345.2"];
    $api->ticket(456)->outage()->update($outage);

Response

PATCH tickets/<ticketId>/outage

Path parameters

Name	Type	Description
ticketId `required`	`integer`	Ticket ID

Request headers

Name	Type	Description
Content-Type `required`	`application/json`

Request body (JSON)

Property	Type	Description
startedAt `optional`	`datetime`	Start of outage
endedAt `optional`	`datetime`ǀ`null`	End of outage or `null` if undefined
affectedPower `optional`	`number`	Affected power in kW
shouldInfluenceAvailability `optional`	`bool`	`true` if outage should affect availability
shouldInfluencePr `optional`	`bool`	`true` if outage should affect performance ratio
components `optional`¹	`array`	Component ID `string`

¹ Only inverters accepted for Component ID.

Response

The response body is empty.

Http-Code: 204

Replace an outage

Request

curl -i -X PUT \
    -H "Content-Type:application/json" \
    -d \
'{
  "startedAt": "2016-11-15T10:00:00+01:00",
  "endedAt": "2016-11-15T10:59:59+01:00",
  "affectedPower": 24.03,
  "shouldInfluenceAvailability": false,
  "shouldInfluencePr": false,
  "components": ["Id12345.1", "Id12345.2"]
}' \
 'https://api.meteocontrol.de/v2/tickets/456/outage'

<?php
    $outage = new Outage();
    $outage->startedAt = new DateTime("2016-11-15T10:00:00+01:00");
    $outage->endedAt = new DateTime("2016-11-15T10:59:59+01:00");
    $outage->affectedPower = 24.03;
    $outage->shouldInfluenceAvailability = false;
    $outage->shouldInfluencePr = false;
    $outage->components = ["Id12345.1", "Id12345.2"];
    $api->ticket(456)->outage()->replace($outage);

Response

PUT tickets/<ticketId>/outage

Path parameters

Name	Type	Description
ticketId `required`	`integer`	Ticket ID

Request headers

Name	Type	Description
Content-Type `required`	`application/json`

Request body (JSON)

Property	Type	Description
startedAt `required`	`datetime`	Start of outage
endedAt `required`	`datetime`ǀ`null`	End of outage or `null` if undefined
affectedPower `required`	`number`	Affected power in kW
shouldInfluenceAvailability `required`	`bool`	`true` if outage should affect availability
shouldInfluencePr `required`	`bool`	`true` if outage should affect performance ratio
components `required`¹	`array`	Component ID `string`

¹ Only inverters accepted for Component ID.

Response

The response body is empty.

Http-Code: 204

Delete an outage

Request

curl -i -X DELETE 'https://api.meteocontrol.de/v2/tickets/456/outage'

<?php
    $api->ticket(456)->outage()->delete();

Response

DELETE tickets/<ticketId>/outage

Path parameters

Name	Type	Description
ticketId `required`	`integer`	Ticket ID

Response

The response body is empty.

Status code	Description
`204`	The outage has been successfully deleted
`403`	User is not authorized to access ticket or outage

Attachments

Get all attachments

Request

curl 'https://api.meteocontrol.de/v2/tickets/123/attachments'

<?php
    /** @var array attachments */
    $attachments = $api->ticket(123)->attachments()->get();

Response

{
  "data":[
    {
      "attachmentId": 1234,
      "filename": "attachment1.jpg",
      "description": "description 1"
    },
    {
      "attachmentId": 5678,
      "filename": "attachment2.jpg",
      "description": "description 2"
    }
  ]
}

<?php
    /** @var array $attachments */
    echo $attachments[0]['attachmentId'];// 1234
    echo $attachments[0]['filename'];// "attachment1.jpg"
    echo $attachments[0]['description'];// "description 1"
    echo $attachments[1]['attachmentId'];// 5678
    echo $attachments[1]['filename'];// "attachment2.jpg"
    echo $attachments[1]['description'];// "description 2"

GET tickets/<ticketId>/attachments

Path parameters

Name	Type	Description
ticketId `required`	`integer`	Ticket ID

Response

Attachment array

Property	Type	Description
attachmentId `fixed`	`integer`	Attachment ID
filename `fixed`	`string`	File name
description `fixed`	`string`	Description

Get single attachment

Request

curl 'https://api.meteocontrol.de/v2/tickets/123/attachments/1234'

<?php
    /** @var AttachmentFile $attachmentFile */
    $attachmentFile = $api->ticket(123)->attachment(1234)->get();

Response

{
  "data":{
    "attachmentId": 1234,
    "filename": "attachment1.png",
    "content": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD.....",
    "createdAt": "2016-09-01T10:15:00+02:00",
    "description": "file description",
    "metaData": null,
    "creatorId": 123456
  }
}

<?php
    /** @var AttachmentFile $attachmentFile */
    echo $attachmentFile->attachmentId;// 1234
    echo $attachmentFile->filename;// attachment1.jpg
    echo $attachmentFile->content;// "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD....."
    echo $attachmentFile->createdAt;// DateTime
    echo $attachmentFile->description;// file description
    echo $attachmentFile->metaData;// null
    echo $attachmentFile->creatorId;// 123456

GET tickets/<ticketId>/attachments/<attachmentId>

Path parameters

Name	Type	Description
ticketId `required`	`integer`	Ticket ID
attachmentId `required`	`integer`	Attachment ID

Response

AttachmentFile object

Property	Type	Description
attachmentId `fixed`	`integer`	Attachment ID
filename `fixed`	`string`	File name
content `fixed`	`string`	Data URI (RFC2397) with base64 encoding
createdAt `fixed`	`string`	Created datetime in system timezone
description `fixed`	`string`	File description
metaData `fixed`	`string`	Attachment meta data in JSON format
creatorId `fixed`	`integer`	Creator ID

Create an attachment

Request

curl -i -X POST \
   -H "Content-Type:application/json" \
   -d \
'{
  "filename": "attachment1.jpg",
  "content": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD.....",
  "description": "file description"
}' \
 'https://api.meteocontrol.de/v2/tickets/123/attachments'

<?php
    $content = base64_encode(file_get_contents('attachment1.jpg'));
    $attachmentFile = new AttachmentFile();
    $attachmentFile->filename = 'attachment1.jpg';
    $attachmentFile->content = 'data:image/jpeg;base64,' . $content;
    $attachmentFile->description = "file description";

    /** @var array $result */
    $result = $api->ticket(123)->attachments()->create($attachmentFile);

Response

{
  "data":{
    "attachmentId": 1234,
    "filename": "attachment1.jpg"
  }
}

<?php
    /** @var AttachmentFile $attachmentFile */
    echo $attachmentFile->attachmentId;// 1234
    echo $attachmentFile->filename;// 'attachment1.jpg'

POST tickets/<ticketId>/attachments

Path parameters

Name	Type	Description
ticketId `required`	`integer`	Ticket ID

Request headers

Name	Type	Description
Content-Type `required`	`application/json`

Request body (JSON)

Property	Type	Description
filename `required`	`string`	Filename
content `required`	`string`	Data URI (RFC2397) with base64 encoding²
description `required`	`string`	File description

¹ Please note there’s a limit of 10 attachments per ticket.
² Max decoded file size is 10MB.

Response

Property	Type	Description
attachmentId `fixed`	`integer`	Attachment ID
filename `fixed`	`string`	Name of the new attachment

Status code	Description
`200`	The attachment has been successfully created
`400`	Invalid request body
`413`	Too large attachment²
`422`	Too many attachments¹

Histories

Get all Histories for a ticket

Request

curl 'https://api.meteocontrol.de/v2/tickets/123/histories'

<?php
    /** @var TicketHistory[] histories */
    $histories = $api->ticket(123)->histories()->get();

Response

{
  "data": [
    {
      "createdAt": "2017-08-31T01:41:59+00:00",
      "action": "created",
      "personInCharge": "userB",
      "from": null,
      "to": "userB"
    },
    {
      "createdAt": "2017-08-31T01:42:03+00:00",
      "action": "statusChanged",
      "personInCharge": "userB",
      "from": "open",
      "to": "inProgress"
    },
    {
      "createdAt": "2017-08-31T02:18:51+00:00",
      "action": "assigneeChanged",
      "personInCharge": "userB",
      "from": null,
      "to": "userA"
    },
    {
      "createdAt": "2017-08-31T02:19:41+00:00",
      "action": "assigneeChanged",
      "personInCharge": "userB",
      "from": "userA",
      "to": "userB"
    }
  ]
}

<?php
    /** @var TicketHistory $histories */
    echo $histories[0]->createdAt->format(DATE_ATOM); // 2017-08-31T01:41:59+00:00
    echo $histories[0]->action; // created
    echo $histories[0]->personInCharge; // userB
    echo $histories[0]->from; // null
    echo $histories[0]->to; // userB
    echo $histories[1]->createdAt->format(DATE_ATOM); // 2017-08-31T01:42:03+00:00
    echo $histories[1]->action; // statusChanged
    echo $histories[1]->personInCharge; // userB
    echo $histories[1]->from; // open
    echo $histories[1]->to; // inProgress
    echo $histories[2]->createdAt->format(DATE_ATOM); // 2017-08-31T02:18:51+00:00
    echo $histories[2]->action; // assigneeChanged
    echo $histories[2]->personInCharge; // userB
    echo $histories[2]->from; // null
    echo $histories[2]->to; // userA
    echo $histories[3]->createdAt->format(DATE_ATOM); // 2017-08-31T02:19:41+00:00
    echo $histories[3]->action; // assigneeChanged
    echo $histories[3]->personInCharge; // userB
    echo $histories[3]->from; // userA
    echo $histories[3]->to; // userB

GET tickets/<ticketId>/histories

Path parameters

Name	Type	Description
ticketId `required`	`integer`	Ticket ID

Response

TicketHistory object

Property	Type	Description
createdAt `fixed`	`datetime`	Created date in system timezone
action `fixed`	`string`	(`created`ǀ`statusChanged`ǀ`assigneeChanged`)
personInCharge	`string`	Updater
from	`string`	Username or state
to	`string`	Username or state

Yield losses

Get yield loss calculation of the ticket

Request

curl 'https://api.meteocontrol.de/v2/tickets/456/yield-losses'

<?php
    /** @var YieldLossCalculation $yieldLosses*/
    $yieldLosses = $api->ticket(456)->yieldLosses()->get();

Response

{
  "data": {
    "model": "reference-system",
    "result": 69.32,
    "realLostYield": 41.29,
    "totalCompensation": 7.34962,
    "comment": ""
  }
}

<?php
    /** @var YieldLossCalculation $yieldLosses */
    echo $yieldLosses->model;// reference-system
    echo $yieldLosses->result;// 69.32
    echo $yieldLosses->realLostYield;// 41.29
    echo $yieldLosses->totalCompensation;// 7.34962
    echo $yieldLosses->comment;// ""

GET tickets/<ticketId>/yield-losses

Path parameters

Name	Type	Description
ticketId `required`	`integer`	Ticket ID

Response

Status code	Description
`200`	Return existing YieldLossCalculation object
`404`	YieldLossCalculation object not found of the ticket id

Flat-rate (energy trader)

Calculate the yield loss using the flat-rate model with energy trader source data

Reference: Bundesnetzagentur (2020). 3.2.3.3 Pauschal-Abrechnung. In Bilanzierungsmodelle und Bestimmung der Ausfallarbeit (p. 10).

Request

curl 'https://api.meteocontrol.de/v2/tickets/45678/yield-losses/flat-rate/energy-trader?from=2022-05-01T00:00:00+00:00&to=2022-05-31T23:59:59+00:00&resolution=900'

<?php
    $yieldLossesCriteria = (new YieldLossesCriteria())
        ->withDateFrom(DateTime::createFromFormat(DATE_ATOM, '2022-05-01T00:00:00+00:00'))
        ->withDateTo(DateTime::createFromFormat(DATE_ATOM, '2022-05-31T23:59:59+00:00'))
        ->withResolution(900);
    /** @var CalculationResult $calculationResult */
    $calculationResult = $api->ticket(45678)->yieldLosses()->flatRate()->energyTrader()
        ->get($yieldLossesCriteria);

Response

{
  "data":{
    "result": 69.32,
    "realLostYield": 41.29,
    "totalCompensation": 7.34962,
    "comment": ""
  }
}

<?php
    /** @var CalculationResult $calculationResult */
    echo $calculationResult->result;// 69.32
    echo $calculationResult->realLostYield;// 41.29
    echo $calculationResult->totalCompensation;// 7.34962
    echo $calculationResult->comment;// ""

GET tickets/<ticketId>/yield-losses/flat-rate/energy-trader

Path parameters

Name	Type	Description
ticketId `required`	`integer`	Ticket ID

Query parameters

Name	Type	Description
from `required`	`date`ǀ`datetime`	Start date
to `required`	`date`ǀ`datetime`	End date
resolution `optional`	`integer`	Resolution in seconds¹

¹ Only 900 seconds is supported. Default resolution uses datalogger interval.

Response

CalculationResult object

Property	Type	Description
result `fixed`	`number`	Calculated yield loss value
realLostYield `fixed`	`number`	Correction yield loss value (if not specified, the value will be the same as `result`)
totalCompensation `fixed`	`number`	Estimation amount of the financial compensation (based on the value of `realLostYield`)
comment `fixed`	`string`	Comment

Calculate the yield loss using the flat-rate model with energy trader source data and save the result

Will create a new record of the yield loss calculation result in the database or rewrite the record if one exists.

Request

curl -i -X PUT \
   -H 'Content-Type:application/json' \
   -d \
'{
  "comment": "New comment"
}' \ 
  'https://api.meteocontrol.de/v2/tickets/45678/yield-losses/flat-rate/energy-trader?from=2022-05-01T00:00:00+00:00&to=2022-05-31T23:59:59+00:00&resolution=900'

<?php
    $yieldLossesCriteria = (new YieldLossesCriteria())
        ->withDateFrom(DateTime::createFromFormat(DATE_ATOM, '2022-05-01T00:00:00+00:00'))
        ->withDateTo(DateTime::createFromFormat(DATE_ATOM, '2022-05-31T23:59:59+00:00'))
        ->withResolution(900);

    $yieldLoss = new YieldLoss();
    $yieldLoss->comment = 'New comment';

    $api->ticket(45678)->yieldLosses()->flatRate()->energyTrader()
        ->replace($yieldLossesCriteria, $yieldLoss);

Response

PUT tickets/<ticketId>/yield-losses/flat-rate/energy-trader

Path parameters

Name	Type	Description
ticketId `required`	`integer`	Ticket ID

Query parameters

Name	Type	Description
from `required`	`date`ǀ`datetime`	Start date
to `required`	`date`ǀ`datetime`	End date
resolution `optional`	`integer`	Resolution in seconds¹

¹ Only 900 seconds is supported. Default resolution uses datalogger interval.

Request headers

Name	Type	Description
Content-Type `required`	`application/json`

Request body (JSON)

Property	Type	Description
comment `required`	`string`ǀ`null`	Comment

Response

The response body is empty.

Http-Code: 204

Flat-rate (grid operator)

Calculate the yield loss using the flat-rate model with grid operator source data

Reference: Bundesnetzagentur (2020). 3.2.3.3 Pauschal-Abrechnung. In Bilanzierungsmodelle und Bestimmung der Ausfallarbeit (p. 10).

Request

curl 'https://api.meteocontrol.de/v2/tickets/45678/yield-losses/flat-rate/grid-operator?from=2022-05-01T00:00:00+00:00&to=2022-05-31T23:59:59+00:00&resolution=900'

<?php
    $yieldLossesCriteria = (new YieldLossesCriteria())
        ->withDateFrom(DateTime::createFromFormat(DATE_ATOM, '2022-05-01T00:00:00+00:00'))
        ->withDateTo(DateTime::createFromFormat(DATE_ATOM, '2022-05-31T23:59:59+00:00'))
        ->withResolution(900);
    /** @var CalculationResult $calculationResult */
    $calculationResult = $api->ticket(45678)->yieldLosses()->flatRate()->gridOperator()
        ->get($yieldLossesCriteria);

Response

{
  "data":{
    "result": 69.32,
    "realLostYield": 41.29,
    "totalCompensation": 7.34962,
    "comment": ""
  }
}

<?php
    /** @var CalculationResult $calculationResult */
    echo $calculationResult->result;// 69.32
    echo $calculationResult->realLostYield;// 41.29
    echo $calculationResult->totalCompensation;// 7.34962
    echo $calculationResult->comment;// ""

GET tickets/<ticketId>/yield-losses/flat-rate/grid-operator

Path parameters

Name	Type	Description
ticketId `required`	`integer`	Ticket ID

Query parameters

Name	Type	Description
from `required`	`date`ǀ`datetime`	Start date
to `required`	`date`ǀ`datetime`	End date
resolution `optional`	`integer`	Resolution in seconds¹

¹ Only 900 seconds is supported. Default resolution uses datalogger interval.

Response

CalculationResult object

Property	Type	Description
result `fixed`	`number`	Calculated yield loss value
realLostYield `fixed`	`number`	Correction yield loss value (if not specified, the value will be the same as `result`)
totalCompensation `fixed`	`number`	Estimation amount of the financial compensation (based on the value of `realLostYield`)
comment `fixed`	`string`	Comment

Calculate the yield loss using the flat-rate model with grid operator source data and save the result

Will create a new record of the yield loss calculation result in the database or rewrite the record if one exists.

Request

curl -i -X PUT \
   -H 'Content-Type:application/json' \
   -d \
'{
  "comment": "New comment"
}' \ 
  'https://api.meteocontrol.de/v2/tickets/45678/yield-losses/flat-rate/grid-operator?from=2022-05-01T00:00:00+00:00&to=2022-05-31T23:59:59+00:00&resolution=900'

<?php
    $yieldLossesCriteria = (new YieldLossesCriteria())
        ->withDateFrom(DateTime::createFromFormat(DATE_ATOM, '2022-05-01T00:00:00+00:00'))
        ->withDateTo(DateTime::createFromFormat(DATE_ATOM, '2022-05-31T23:59:59+00:00'))
        ->withResolution(900);

    $yieldLoss = new YieldLoss();
    $yieldLoss->comment = 'New comment';

    $api->ticket(45678)->yieldLosses()->flatRate()->gridOperator()
        ->replace($yieldLossesCriteria, $yieldLoss);

Response

PUT tickets/<ticketId>/yield-losses/flat-rate/grid-operator

Path parameters

Name	Type	Description
ticketId `required`	`integer`	Ticket ID

Query parameters

Name	Type	Description
from `required`	`date`ǀ`datetime`	Start date
to `required`	`date`ǀ`datetime`	End date
resolution `optional`	`integer`	Resolution in seconds¹

¹ Only 900 seconds is supported. Default resolution uses datalogger interval.

Request headers

Name	Type	Description
Content-Type `required`	`application/json`

Request body (JSON)

Property	Type	Description
comment `required`	`string`ǀ`null`	Comment

Response

The response body is empty.

Http-Code: 204

Flat-rate (manual)

Calculate the yield loss using the flat-rate model with manual source data

Reference: Bundesnetzagentur (2020). 3.2.3.3 Pauschal-Abrechnung. In Bilanzierungsmodelle und Bestimmung der Ausfallarbeit (p. 10).

Request

curl 'https://api.meteocontrol.de/v2/tickets/45678/yield-losses/flat-rate/manual?from=2022-05-01T00:00:00+00:00&to=2022-05-31T23:59:59+00:00'

<?php
    $yieldLossesCriteria = (new YieldLossesCriteria())
        ->withDateFrom(DateTime::createFromFormat(DATE_ATOM, '2022-05-01T00:00:00+00:00'))
        ->withDateTo(DateTime::createFromFormat(DATE_ATOM, '2022-05-31T23:59:59+00:00'));
    /** @var CalculationResult $calculationResult */
    $calculationResult = $api->ticket(45678)->yieldLosses()->flatRate()->manual()
        ->get($yieldLossesCriteria);

Response

{
  "data":{
    "result": 69.32,
    "realLostYield": 41.29,
    "totalCompensation": 7.34962,
    "comment": ""
  }
}

<?php
    /** @var CalculationResult $calculationResult */
    echo $calculationResult->result;// 69.32
    echo $calculationResult->realLostYield;// 41.29
    echo $calculationResult->totalCompensation;// 7.34962
    echo $calculationResult->comment;// ""

GET tickets/<ticketId>/yield-losses/flat-rate/manual

Path parameters

Name	Type	Description
ticketId `required`	`integer`	Ticket ID

Query parameters

Name	Type	Description
from `required`	`date`ǀ`datetime`	Start date
to `required`	`date`ǀ`datetime`	End date

Response

CalculationResult object

Property	Type	Description
result `fixed`	`number`	Calculated yield loss value
realLostYield `fixed`	`number`	Correction yield loss value (if not specified, the value will be the same as `result`)
totalCompensation `fixed`	`number`	Estimation amount of the financial compensation (based on the value of `realLostYield`)
comment `fixed`	`string`	Comment

Calculate the yield loss using the flat-rate model with manual source data and save the result

Will create a new record of the yield loss calculation result in the database or rewrite the record if one exists.

Request

curl -i -X PUT \
   -H 'Content-Type:application/json' \
   -d \
'{
  "comment": "New comment"
}' \ 
  'https://api.meteocontrol.de/v2/tickets/45678/yield-losses/flat-rate/manual?from=2022-05-01T00:00:00+00:00&to=2022-05-31T23:59:59+00:00'

<?php
    $yieldLossesCriteria = (new YieldLossesCriteria())
        ->withDateFrom(DateTime::createFromFormat(DATE_ATOM, '2022-05-01T00:00:00+00:00'))
        ->withDateTo(DateTime::createFromFormat(DATE_ATOM, '2022-05-31T23:59:59+00:00'));

    $yieldLoss = new YieldLoss();
    $yieldLoss->comment = 'New comment';

    $api->ticket(45678)->yieldLosses()->flatRate()->manual()
        ->replace($yieldLossesCriteria, $yieldLoss);

Response

PUT tickets/<ticketId>/yield-losses/flat-rate/manual

Path parameters

Name	Type	Description
ticketId `required`	`integer`	Ticket ID

Query parameters

Name	Type	Description
from `required`	`date`ǀ`datetime`	Start date
to `required`	`date`ǀ`datetime`	End date

Request headers

Name	Type	Description
Content-Type `required`	`application/json`

Request body (JSON)

Property	Type	Description
comment `required`	`string`ǀ`null`	Comment

Response

The response body is empty.

Http-Code: 204

Flat-rate (static)

Calculate the yield loss using the flat-rate model with static source data

Reference: Bundesnetzagentur (2020). 3.2.3.3 Pauschal-Abrechnung. In Bilanzierungsmodelle und Bestimmung der Ausfallarbeit (p. 10).

Request

curl 'https://api.meteocontrol.de/v2/tickets/45678/yield-losses/flat-rate/static?from=2022-05-01T00:00:00+00:00&to=2022-05-31T23:59:59+00:00'

<?php
    $yieldLossesCriteria = (new YieldLossesCriteria())
        ->withDateFrom(DateTime::createFromFormat(DATE_ATOM, '2022-05-01T00:00:00+00:00'))
        ->withDateTo(DateTime::createFromFormat(DATE_ATOM, '2022-05-31T23:59:59+00:00'));
    /** @var CalculationResult $calculationResult */
    $calculationResult = $api->ticket(45678)->yieldLosses()->flatRate()->static()
        ->get($yieldLossesCriteria);

Response

{
  "data":{
    "result": 69.32,
    "realLostYield": 41.29,
    "totalCompensation": 7.34962,
    "comment": ""
  }
}

<?php
    /** @var CalculationResult $calculationResult */
    echo $calculationResult->result;// 69.32
    echo $calculationResult->realLostYield;// 41.29
    echo $calculationResult->totalCompensation;// 7.34962
    echo $calculationResult->comment;// ""

GET tickets/<ticketId>/yield-losses/flat-rate/static

Path parameters

Name	Type	Description
ticketId `required`	`integer`	Ticket ID

Query parameters

Name	Type	Description
from `required`	`date`ǀ`datetime`	Start date
to `required`	`date`ǀ`datetime`	End date

Response

CalculationResult object

Property	Type	Description
result `fixed`	`number`	Calculated yield loss value
realLostYield `fixed`	`number`	Correction yield loss value (if not specified, the value will be the same as `result`)
totalCompensation `fixed`	`number`	Estimation amount of the financial compensation (based on the value of `realLostYield`)
comment `fixed`	`string`	Comment

Calculate the yield loss using the flat-rate model with static source data and save the result

Will create a new record of the yield loss calculation result in the database or rewrite the record if one exists.

Request

curl -i -X PUT \
   -H 'Content-Type:application/json' \
   -d \
'{
  "comment": "New comment"
}' \ 
  'https://api.meteocontrol.de/v2/tickets/45678/yield-losses/flat-rate/static?from=2022-05-01T00:00:00+00:00&to=2022-05-31T23:59:59+00:00'

<?php
    $yieldLossesCriteria = (new YieldLossesCriteria())
        ->withDateFrom(DateTime::createFromFormat(DATE_ATOM, '2022-05-01T00:00:00+00:00'))
        ->withDateTo(DateTime::createFromFormat(DATE_ATOM, '2022-05-31T23:59:59+00:00'));

    $yieldLoss = new YieldLoss();
    $yieldLoss->comment = 'New comment';

    $api->ticket(45678)->yieldLosses()->flatRate()->static()
        ->replace($yieldLossesCriteria, $yieldLoss);

Response

PUT tickets/<ticketId>/yield-losses/flat-rate/static

Path parameters

Name	Type	Description
ticketId `required`	`integer`	Ticket ID

Query parameters

Name	Type	Description
from `required`	`date`ǀ`datetime`	Start date
to `required`	`date`ǀ`datetime`	End date

Request headers

Name	Type	Description
Content-Type `required`	`application/json`

Request body (JSON)

Property	Type	Description
comment `required`	`string`ǀ`null`	Comment

Response

The response body is empty.

Http-Code: 204

Flat-rate (undetermined)

Calculate the yield loss using the flat-rate model with undetermined source data

Reference: Bundesnetzagentur (2020). 3.2.3.3 Pauschal-Abrechnung. In Bilanzierungsmodelle und Bestimmung der Ausfallarbeit (p. 10).

Request

curl 'https://api.meteocontrol.de/v2/tickets/56789/yield-losses/flat-rate/undetermined?from=2025-07-01T00:00:00+00:00&to=2025-07-01T23:59:59+00:00'

<?php
    $yieldLossesCriteria = (new YieldLossesCriteria())
        ->withDateFrom(DateTime::createFromFormat(DATE_ATOM, '2025-07-01T00:00:00+00:00'))
        ->withDateTo(DateTime::createFromFormat(DATE_ATOM, '2025-07-01T23:59:59+00:00'));
    /** @var CalculationResult $calculationResult */
    $calculationResult = $api->ticket(56789)->yieldLosses()->flatRate()->undetermined()
        ->get($yieldLossesCriteria);

Response

{
  "data":{
    "result": 69.32,
    "realLostYield": 41.29,
    "totalCompensation": 7.34962,
    "comment": ""
  }
}

<?php
    /** @var CalculationResult $calculationResult */
    echo $calculationResult->result;// 69.32
    echo $calculationResult->realLostYield;// 41.29
    echo $calculationResult->totalCompensation;// 7.34962
    echo $calculationResult->comment;// ""

GET tickets/<ticketId>/yield-losses/flat-rate/undetermined

Path parameters

Name	Type	Description
ticketId `required`	`integer`	Ticket ID

Query parameters

Name	Type	Description
from `required`	`date`ǀ`datetime`	Start date
to `required`	`date`ǀ`datetime`	End date

Response

CalculationResult object

Property	Type	Description
result `fixed`	`number`	Calculated yield loss value
realLostYield `fixed`	`number`	Correction yield loss value (if not specified, the value will be the same as `result`)
totalCompensation `fixed`	`number`	Estimation amount of the financial compensation (based on the value of `realLostYield`)
comment `fixed`	`string`	Comment

Calculate the yield loss using the flat-rate model with undetermined source data and save the result

Will create a new record of the yield loss calculation result in the database or rewrite the record if one exists.

Request

curl -i -X PUT \
   -H 'Content-Type:application/json' \
   -d \
'{
  "comment": "New comment"
}' \ 
  'https://api.meteocontrol.de/v2/tickets/56789/yield-losses/flat-rate/undetermined?from=2025-07-01T00:00:00+00:00&to=2025-07-01T23:59:59+00:00'

<?php
    $yieldLossesCriteria = (new YieldLossesCriteria())
        ->withDateFrom(DateTime::createFromFormat(DATE_ATOM, '2025-07-01T00:00:00+00:00'))
        ->withDateTo(DateTime::createFromFormat(DATE_ATOM, '2025-07-01T23:59:59+00:00'));

    $yieldLoss = new YieldLoss();
    $yieldLoss->comment = 'New comment';

    $api->ticket(56789)->yieldLosses()->flatRate()->undetermined()
        ->replace($yieldLossesCriteria, $yieldLoss);

Response

PUT tickets/<ticketId>/yield-losses/flat-rate/undetermined

Path parameters

Name	Type	Description
ticketId `required`	`integer`	Ticket ID

Query parameters

Name	Type	Description
from `required`	`date`ǀ`datetime`	Start date
to `required`	`date`ǀ`datetime`	End date

Request headers

Name	Type	Description
Content-Type `required`	`application/json`

Request body (JSON)

Property	Type	Description
comment `required`	`string`ǀ`null`	Comment

Response

The response body is empty.

Http-Code: 204

Linear equation

Calculate the yield loss using the linear equation model

Request

curl 'https://api.meteocontrol.de/v2/tickets/456/yield-losses/linear-equation?from=2016-11-15T10:00:00+01:00&to=2016-11-15T10:59:59+01:00&referenceFrom=2016-11-15T14:50:00+01:00&referenceTo=2016-11-15T15:50:00+01:00'

<?php
    $linearEquationCriteria = (new LinearEquationCriteria())
        ->withDateFrom(DateTime::createFromFormat(DATE_ATOM, '2016-11-15T10:00:00+00:00'))
        ->withDateTo(DateTime::createFromFormat(DATE_ATOM, '2016-11-15T10:59:59+00:00'))
        ->withDateReferenceFrom(DateTime::createFromFormat(DATE_ATOM, '2016-11-15T14:50:00+00:00'))
        ->withDateReferenceTo(DateTime::createFromFormat(DATE_ATOM, '2016-11-15T15:50:00+00:00'));
    /** @var CalculationResult $calculationResult */
    $calculationResult = $api->ticket(456)->yieldLosses()->linearEquation()
        ->get($linearEquationCriteria);

Response

{
  "data":{
    "result": 69.32,
    "realLostYield": 41.29,
    "totalCompensation": 7.34962,
    "comment": ""
  }
}

<?php
    /** @var CalculationResult $calculationResult */
    echo $calculationResult->result;// 69.32
    echo $calculationResult->realLostYield;// 41.29
    echo $calculationResult->totalCompensation;// 7.34962
    echo $calculationResult->comment;// ""

GET tickets/<ticketId>/yield-losses/linear-equation

Path parameters

Name	Type	Description
ticketId `required`	`integer`	Ticket ID

Query parameters

Name	Type	Description
from `required`	`date`ǀ`datetime`	Start date
to `required`	`date`ǀ`datetime`	End date
referenceFrom `required`	`date`ǀ`datetime`	Reference start date
referenceTo `required`	`date`ǀ`datetime`	Reference end date

Response

CalculationResult object

Property	Type	Description
result `fixed`	`number`	Calculated yield loss value
realLostYield `fixed`	`number`	Correction yield loss value (if not specified, the value will be the same as `result`)
totalCompensation `fixed`	`number`	Estimation amount of the financial compensation (based on the value of `realLostYield`)
comment `fixed`	`string`	Comment

Calculate the yield loss using the linear equation model and save the result

Will create a new record of the yield loss calculation result in the database or rewrite the record if one exists.

Request

curl -i -X PUT \
   -H 'Content-Type:application/json' \
   -d \
'{
  "realLostYield": 42.38,
  "comment": "New comment"
}' \ 
  'https://api.meteocontrol.de/v2/tickets/456/yield-losses/linear-equation?from=2016-11-15T10:00:00+01:00&to=2016-11-15T10:59:59+01:00&referenceFrom=2016-11-15T14:50:00+01:00&referenceTo=2016-11-15T15:50:00+01:00'

<?php
    $linearEquationCriteria = (new LinearEquationCriteria())
        ->withDateFrom(DateTime::createFromFormat(DATE_ATOM, '2016-11-15T10:00:00+00:00'))
        ->withDateTo(DateTime::createFromFormat(DATE_ATOM, '2016-11-15T10:59:59+00:00'))
        ->withDateReferenceFrom(DateTime::createFromFormat(DATE_ATOM, '2016-11-15T14:50:00+00:00'))
        ->withDateReferenceTo(DateTime::createFromFormat(DATE_ATOM, '2016-11-15T15:50:00+00:00'));

    $yieldLoss = new YieldLoss();
    $yieldLoss->realLostYield = 42.38;
    $yieldLoss->comment = 'New comment';

    $api->ticket(456)->yieldLosses()->linearEquation()
        ->replace($linearEquationCriteria, $yieldLoss);

Response

PUT tickets/<ticketId>/yield-losses/linear-equation

Path parameters

Name	Type	Description
ticketId `required`	`integer`	Ticket ID

Query parameters

Name	Type	Description
from `required`	`date`ǀ`datetime`	Start date
to `required`	`date`ǀ`datetime`	End date
referenceFrom `required`	`date`ǀ`datetime`	Reference start date
referenceTo `required`	`date`ǀ`datetime`	Reference end date

Request headers

Name	Type	Description
Content-Type `required`	`application/json`

Request body (JSON)

Property	Type	Description
realLostYield `required`	`number`ǀ`null`	Correction yield loss value
comment `required`	`string`ǀ`null`	Comment

Response

The response body is empty.

Http-Code: 204

Peak (energy trader)

Calculate the yield loss using the peak model with energy trader source data

Reference: Bundesnetzagentur (2020). 3.2.3.1 Spitzabrechnung. In Bilanzierungsmodelle und Bestimmung der Ausfallarbeit (p. 9).

Request

curl 'https://api.meteocontrol.de/v2/tickets/45678/yield-losses/peak/energy-trader?from=2021-05-05T00:00:00+00:00&to=2021-05-10T23:59:59+00:00&resolution=900'

<?php
    $yieldLossesCriteria = (new YieldLossesCriteria())
        ->withDateFrom(DateTime::createFromFormat(DATE_ATOM, '2021-05-05T00:00:00+00:00'))
        ->withDateTo(DateTime::createFromFormat(DATE_ATOM, '2021-05-10T23:59:59+00:00'))
        ->withResolution(900);
    /** @var CalculationResult $calculationResult */
    $calculationResult = $api->ticket(45678)->yieldLosses()->peak()->energyTrader()
        ->get($yieldLossesCriteria);

Response

{
  "data":{
    "result": 69.32,
    "realLostYield": 41.29,
    "totalCompensation": 7.34962,
    "comment": ""
  }
}

<?php
    /** @var CalculationResult $calculationResult */
    echo $calculationResult->result;// 69.32
    echo $calculationResult->realLostYield;// 41.29
    echo $calculationResult->totalCompensation;// 7.34962
    echo $calculationResult->comment;// ""

GET tickets/<ticketId>/yield-losses/peak/energy-trader

Path parameters

Name	Type	Description
ticketId `required`	`integer`	Ticket ID

Query parameters

Name	Type	Description
from `required`	`date`ǀ`datetime`	Start date
to `required`	`date`ǀ`datetime`	End date
resolution `optional`	`integer`	Resolution in seconds¹

¹ Only 900 seconds is supported. Default resolution uses datalogger interval.

Response

CalculationResult object

Property	Type	Description
result `fixed`	`number`	Calculated yield loss value
realLostYield `fixed`	`number`	Correction yield loss value (if not specified, the value will be the same as `result`)
totalCompensation `fixed`	`number`	Estimation amount of the financial compensation (based on the value of `realLostYield`)
comment `fixed`	`string`	Comment

Calculate the yield loss using the peak model with energy trader source data and save the result

Will create a new record of the yield loss calculation result in the database or rewrite the record if one exists.

Request

curl -i -X PUT \
   -H 'Content-Type:application/json' \
   -d \
'{
  "comment": "New comment"
}' \ 
  'https://api.meteocontrol.de/v2/tickets/45678/yield-losses/peak/energy-trader?from=2022-05-25T00:00:00+00:00&to=2022-05-31T23:59:59+00:00&resolution=900'

<?php
    $yieldLossesCriteria = (new YieldLossesCriteria())
        ->withDateFrom(DateTime::createFromFormat(DATE_ATOM, '2022-05-25T00:00:00+00:00'))
        ->withDateTo(DateTime::createFromFormat(DATE_ATOM, '2022-05-31T23:59:59+00:00'))
        ->withResolution(900);

    $yieldLoss = new YieldLoss();
    $yieldLoss->comment = 'New comment';

    $api->ticket(45678)->yieldLosses()->peak()->energyTrader()
        ->replace($yieldLossesCriteria, $yieldLoss);

Response

PUT tickets/<ticketId>/yield-losses/peak/energy-trader

Path parameters

Name	Type	Description
ticketId `required`	`integer`	Ticket ID

Query parameters

Name	Type	Description
from `required`	`date`ǀ`datetime`	Start date
to `required`	`date`ǀ`datetime`	End date
resolution `optional`	`integer`	Resolution in seconds¹

¹ Only 900 seconds is supported. Default resolution uses datalogger interval.

Request headers

Name	Type	Description
Content-Type `required`	`application/json`

Request body (JSON)

Property	Type	Description
comment `required`	`string`ǀ`null`	Comment

Response

The response body is empty.

Http-Code: 204

Peak (grid operator)

Calculate the yield loss using the peak model with grid operator source data

Reference: Bundesnetzagentur (2020). 3.2.3.1 Spitzabrechnung. In Bilanzierungsmodelle und Bestimmung der Ausfallarbeit (p. 9).

Request

curl 'https://api.meteocontrol.de/v2/tickets/45678/yield-losses/peak/grid-operator?from=2022-05-25T00:00:00+00:00&to=2022-05-31T23:59:59+00:00'

<?php
    $yieldLossesCriteria = (new YieldLossesCriteria())
        ->withDateFrom(DateTime::createFromFormat(DATE_ATOM, '2022-05-25T00:00:00+00:00'))
        ->withDateTo(DateTime::createFromFormat(DATE_ATOM, '2022-05-31T23:59:59+00:00'));
    /** @var CalculationResult $calculationResult */
    $calculationResult = $api->ticket(45678)->yieldLosses()->peak()->gridOperator()
        ->get($yieldLossesCriteria);

Response

{
  "data":{
    "result": 69.32,
    "realLostYield": 41.29,
    "totalCompensation": 7.34962,
    "comment": ""
  }
}

<?php
    /** @var CalculationResult $calculationResult */
    echo $calculationResult->result;// 69.32
    echo $calculationResult->realLostYield;// 41.29
    echo $calculationResult->totalCompensation;// 7.34962
    echo $calculationResult->comment;// ""

GET tickets/<ticketId>/yield-losses/peak/grid-operator

Path parameters

Name	Type	Description
ticketId `required`	`integer`	Ticket ID

Query parameters

Name	Type	Description
from `required`	`date`ǀ`datetime`	Start date
to `required`	`date`ǀ`datetime`	End date

Response

CalculationResult object

Property	Type	Description
result `fixed`	`number`	Calculated yield loss value
realLostYield `fixed`	`number`	Correction yield loss value (if not specified, the value will be the same as `result`)
totalCompensation `fixed`	`number`	Estimation amount of the financial compensation (based on the value of `realLostYield`)
comment `fixed`	`string`	Comment

Calculate the yield loss using the peak model with grid operator source data and save the result

Will create a new record of the yield loss calculation result in the database or rewrite the record if one exists.

Request

curl -i -X PUT \
   -H 'Content-Type:application/json' \
   -d \
'{
  "comment": "New comment"
}' \ 
  'https://api.meteocontrol.de/v2/tickets/45678/yield-losses/peak/grid-operator?from=2022-05-25T00:00:00+00:00&to=2022-05-31T23:59:59+00:00'

<?php
    $yieldLossesCriteria = (new YieldLossesCriteria())
        ->withDateFrom(DateTime::createFromFormat(DATE_ATOM, '2022-05-25T00:00:00+00:00'))
        ->withDateTo(DateTime::createFromFormat(DATE_ATOM, '2022-05-31T23:59:59+00:00'));

    $yieldLoss = new YieldLoss();
    $yieldLoss->comment = 'New comment';

    $api->ticket(45678)->yieldLosses()->peak()->gridOperator()
        ->replace($yieldLossesCriteria, $yieldLoss);

Response

PUT tickets/<ticketId>/yield-losses/peak/grid-operator

Path parameters

Name	Type	Description
ticketId `required`	`integer`	Ticket ID

Query parameters

Name	Type	Description
from `required`	`date`ǀ`datetime`	Start date
to `required`	`date`ǀ`datetime`	End date

Request headers

Name	Type	Description
Content-Type `required`	`application/json`

Request body (JSON)

Property	Type	Description
comment `required`	`string`ǀ`null`	Comment

Response

The response body is empty.

Http-Code: 204

Peak (manual)

Calculate the yield loss using the peak model with manual source data

Reference: Bundesnetzagentur (2020). 3.2.3.1 Spitzabrechnung. In Bilanzierungsmodelle und Bestimmung der Ausfallarbeit (p. 9).

Request

curl 'https://api.meteocontrol.de/v2/tickets/45678/yield-losses/peak/manual?from=2022-05-25T00:00:00+00:00&to=2022-05-31T23:59:59+00:00'

<?php
    $yieldLossesCriteria = (new YieldLossesCriteria())
        ->withDateFrom(DateTime::createFromFormat(DATE_ATOM, '2022-05-25T00:00:00+00:00'))
        ->withDateTo(DateTime::createFromFormat(DATE_ATOM, '2022-05-31T23:59:59+00:00'));
    /** @var CalculationResult $calculationResult */
    $calculationResult = $api->ticket(45678)->yieldLosses()->peak()->manual()
        ->get($yieldLossesCriteria);

Response

{
  "data":{
    "result": 69.32,
    "realLostYield": 41.29,
    "totalCompensation": 7.34962,
    "comment": ""
  }
}

<?php
    /** @var CalculationResult $calculationResult */
    echo $calculationResult->result;// 69.32
    echo $calculationResult->realLostYield;// 41.29
    echo $calculationResult->totalCompensation;// 7.34962
    echo $calculationResult->comment;// ""

GET tickets/<ticketId>/yield-losses/peak/manual

Path parameters

Name	Type	Description
ticketId `required`	`integer`	Ticket ID

Query parameters

Name	Type	Description
from `required`	`date`ǀ`datetime`	Start date
to `required`	`date`ǀ`datetime`	End date

Response

CalculationResult object

Property	Type	Description
result `fixed`	`number`	Calculated yield loss value
realLostYield `fixed`	`number`	Correction yield loss value (if not specified, the value will be the same as `result`)
totalCompensation `fixed`	`number`	Estimation amount of the financial compensation (based on the value of `realLostYield`)
comment `fixed`	`string`	Comment

Calculate the yield loss using the peak model with manual source data and save the result

Will create a new record of the yield loss calculation result in the database or rewrite the record if one exists.

Request

curl -i -X PUT \
   -H 'Content-Type:application/json' \
   -d \
'{
  "comment": "New comment"
}' \ 
  'https://api.meteocontrol.de/v2/tickets/45678/yield-losses/peak/manual?from=2022-05-25T00:00:00+00:00&to=2022-05-31T23:59:59+00:00'

<?php
    $yieldLossesCriteria = (new YieldLossesCriteria())
        ->withDateFrom(DateTime::createFromFormat(DATE_ATOM, '2022-05-25T00:00:00+00:00'))
        ->withDateTo(DateTime::createFromFormat(DATE_ATOM, '2022-05-31T23:59:59+00:00'));

    $yieldLoss = new YieldLoss();
    $yieldLoss->comment = 'New comment';

    $api->ticket(45678)->yieldLosses()->peak()->manual()
        ->replace($yieldLossesCriteria, $yieldLoss);

Response

PUT tickets/<ticketId>/yield-losses/peak/manual

Path parameters

Name	Type	Description
ticketId `required`	`integer`	Ticket ID

Query parameters

Name	Type	Description
from `required`	`date`ǀ`datetime`	Start date
to `required`	`date`ǀ`datetime`	End date

Request headers

Name	Type	Description
Content-Type `required`	`application/json`

Request body (JSON)

Property	Type	Description
comment `required`	`string`ǀ`null`	Comment

Response

The response body is empty.

Http-Code: 204

Peak (static)

Calculate the yield loss using the peak model with static source data

Reference: Bundesnetzagentur (2020). 3.2.3.1 Spitzabrechnung. In Bilanzierungsmodelle und Bestimmung der Ausfallarbeit (p. 9).

Request

curl 'https://api.meteocontrol.de/v2/tickets/45678/yield-losses/peak/static?from=2022-05-25T00:00:00+00:00&to=2022-05-31T23:59:59+00:00'

<?php
    $yieldLossesCriteria = (new YieldLossesCriteria())
        ->withDateFrom(DateTime::createFromFormat(DATE_ATOM, '2022-05-25T00:00:00+00:00'))
        ->withDateTo(DateTime::createFromFormat(DATE_ATOM, '2022-05-31T23:59:59+00:00'));
    /** @var CalculationResult $calculationResult */
    $calculationResult = $api->ticket(45678)->yieldLosses()->peak()->static()
        ->get($yieldLossesCriteria);

Response

{
  "data":{
    "result": 69.32,
    "realLostYield": 41.29,
    "totalCompensation": 7.34962,
    "comment": ""
  }
}

<?php
    /** @var CalculationResult $calculationResult */
    echo $calculationResult->result;// 69.32
    echo $calculationResult->realLostYield;// 41.29
    echo $calculationResult->totalCompensation;// 7.34962
    echo $calculationResult->comment;// ""

GET tickets/<ticketId>/yield-losses/peak/static

Path parameters

Name	Type	Description
ticketId `required`	`integer`	Ticket ID

Query parameters

Name	Type	Description
from `required`	`date`ǀ`datetime`	Start date
to `required`	`date`ǀ`datetime`	End date

Response

CalculationResult object

Property	Type	Description
result `fixed`	`number`	Calculated yield loss value
realLostYield `fixed`	`number`	Correction yield loss value (if not specified, the value will be the same as `result`)
totalCompensation `fixed`	`number`	Estimation amount of the financial compensation (based on the value of `realLostYield`)
comment `fixed`	`string`	Comment

Calculate the yield loss using the peak model with static source data and save the result

Will create a new record of the yield loss calculation result in the database or rewrite the record if one exists.

Request

curl -i -X PUT \
   -H 'Content-Type:application/json' \
   -d \
'{
  "comment": "New comment"
}' \ 
  'https://api.meteocontrol.de/v2/tickets/45678/yield-losses/peak/static?from=2022-05-25T00:00:00+00:00&to=2022-05-31T23:59:59+00:00'

<?php
    $yieldLossesCriteria = (new YieldLossesCriteria())
        ->withDateFrom(DateTime::createFromFormat(DATE_ATOM, '2022-05-25T00:00:00+00:00'))
        ->withDateTo(DateTime::createFromFormat(DATE_ATOM, '2022-05-31T23:59:59+00:00'));

    $yieldLoss = new YieldLoss();
    $yieldLoss->comment = 'New comment';

    $api->ticket(45678)->yieldLosses()->peak()->static()
        ->replace($yieldLossesCriteria, $yieldLoss);

Response

PUT tickets/<ticketId>/yield-losses/peak/static

Path parameters

Name	Type	Description
ticketId `required`	`integer`	Ticket ID

Query parameters

Name	Type	Description
from `required`	`date`ǀ`datetime`	Start date
to `required`	`date`ǀ`datetime`	End date

Request headers

Name	Type	Description
Content-Type `required`	`application/json`

Request body (JSON)

Property	Type	Description
comment `required`	`string`ǀ`null`	Comment

Response

The response body is empty.

Http-Code: 204

Peak (undetermined)

Calculate the yield loss using the peak model with undetermined source data

Reference: Bundesnetzagentur (2020). 3.2.3.1 Spitzabrechnung. In Bilanzierungsmodelle und Bestimmung der Ausfallarbeit (p. 9).

Request

curl 'https://api.meteocontrol.de/v2/tickets/56789/yield-losses/peak/undetermined?from=2025-07-01T00:00:00+00:00&to=2025-07-01T23:59:59+00:00'

<?php
    $yieldLossesCriteria = (new YieldLossesCriteria())
        ->withDateFrom(DateTime::createFromFormat(DATE_ATOM, '2025-07-01T00:00:00+00:00'))
        ->withDateTo(DateTime::createFromFormat(DATE_ATOM, '2025-07-01T23:59:59+00:00'));
    /** @var CalculationResult $calculationResult */
    $calculationResult = $api->ticket(56789)->yieldLosses()->peak()->undetermined()
        ->get($yieldLossesCriteria);

Response

{
  "data":{
    "result": 69.32,
    "realLostYield": 41.29,
    "totalCompensation": 7.34962,
    "comment": ""
  }
}

<?php
    /** @var CalculationResult $calculationResult */
    echo $calculationResult->result;// 69.32
    echo $calculationResult->realLostYield;// 41.29
    echo $calculationResult->totalCompensation;// 7.34962
    echo $calculationResult->comment;// ""

GET tickets/<ticketId>/yield-losses/peak/undetermined

Path parameters

Name	Type	Description
ticketId `required`	`integer`	Ticket ID

Query parameters

Name	Type	Description
from `required`	`date`ǀ`datetime`	Start date
to `required`	`date`ǀ`datetime`	End date

Response

CalculationResult object

Property	Type	Description
result `fixed`	`number`	Calculated yield loss value
realLostYield `fixed`	`number`	Correction yield loss value (if not specified, the value will be the same as `result`)
totalCompensation `fixed`	`number`	Estimation amount of the financial compensation (based on the value of `realLostYield`)
comment `fixed`	`string`	Comment

Calculate the yield loss using the peak model with undetermined source data and save the result

Will create a new record of the yield loss calculation result in the database or rewrite the record if one exists.

Request

curl -i -X PUT \
   -H 'Content-Type:application/json' \
   -d \
'{
  "comment": "New comment"
}' \ 
  'https://api.meteocontrol.de/v2/tickets/56789/yield-losses/peak/undetermined?from=2025-07-01T00:00:00+00:00&to=2025-07-01T23:59:59+00:00'

<?php
    $yieldLossesCriteria = (new YieldLossesCriteria())
        ->withDateFrom(DateTime::createFromFormat(DATE_ATOM, '2025-07-01T00:00:00+00:00'))
        ->withDateTo(DateTime::createFromFormat(DATE_ATOM, '2025-07-01T23:59:59+00:00'));

    $yieldLoss = new YieldLoss();
    $yieldLoss->comment = 'New comment';

    $api->ticket(56789)->yieldLosses()->peak()->undetermined()
        ->replace($yieldLossesCriteria, $yieldLoss);

Response

PUT tickets/<ticketId>/yield-losses/peak/undetermined

Path parameters

Name	Type	Description
ticketId `required`	`integer`	Ticket ID

Query parameters

Name	Type	Description
from `required`	`date`ǀ`datetime`	Start date
to `required`	`date`ǀ`datetime`	End date

Request headers

Name	Type	Description
Content-Type `required`	`application/json`

Request body (JSON)

Property	Type	Description
comment `required`	`string`ǀ`null`	Comment

Response

The response body is empty.

Http-Code: 204

Reference component

Calculate the yield loss using the reference component model

Request

curl 'https://api.meteocontrol.de/v2/tickets/456/yield-losses/reference-component?from=2016-11-15T10:00:00+00:00&to=2016-11-15T10:59:59+00:00&affectedInverterId=Id12345.4&referenceInverterIds=Id12345.1,Id12345.2'

<?php
    $referenceComponentCriteria = (new ReferenceComponentCriteria())
        ->withDateFrom(DateTime::createFromFormat(DATE_ATOM, '2016-11-15T10:00:00+00:00'))
        ->withDateTo(DateTime::createFromFormat(DATE_ATOM, '2016-11-15T10:59:59+00:00'))
        ->withAffectedInverterId('Id12345.4')
        ->withReferenceInverterIds('Id12345.1,Id12345.2');
    /** @var CalculationResult $calculationResult */
    $calculationResult = $api->ticket(456)->yieldLosses()->referenceComponent()
        ->get($referenceComponentCriteria);

Response

{
  "data":{
    "result": 69.32,
    "realLostYield": 41.29,
    "totalCompensation": 7.34962,
    "comment": ""
  }
}

<?php
    /** @var CalculationResult $calculationResult */
    echo $calculationResult->result;// 69.32
    echo $calculationResult->realLostYield;// 41.29
    echo $calculationResult->totalCompensation;// 7.34962
    echo $calculationResult->comment;// ""

GET tickets/<ticketId>/yield-losses/reference-component

Path parameters

Name	Type	Description
ticketId `required`	`integer`	Ticket ID

Query parameters

Name	Type	Description
from `required`	`date`ǀ`datetime`	Start date
to `required`	`date`ǀ`datetime`	End date
affectedInverterId `required`	`string`	Affected inverter ID
referenceInverterIds `required`	`string`	Reference inverter IDs (comma separated)

Response

CalculationResult object

Property	Type	Description
result `fixed`	`number`	Calculated yield loss value
realLostYield `fixed`	`number`	Correction yield loss value (if not specified, the value will be the same as `result`)
totalCompensation `fixed`	`number`	Estimation amount of the financial compensation (based on the value of `realLostYield`)
comment `fixed`	`string`	Comment

Calculate the yield loss using the reference component model and save the result

Will create a new record of the yield loss calculation result in the database or rewrite the record if one exists.

Request

curl -i -X PUT \
   -H 'Content-Type:application/json' \
   -d \
'{
  "realLostYield": 42.38,
  "comment": "New comment"
}' \ 
  'https://api.meteocontrol.de/v2/tickets/456/yield-losses/reference-component?from=2016-11-15T10:00:00+00:00&to=2016-11-15T10:59:59+00:00&affectedInverterId=Id12345.4&referenceInverterIds=Id12345.1,Id12345.2'

<?php
    $referenceComponentCriteria = (new ReferenceComponentCriteria())
        ->withDateFrom(DateTime::createFromFormat(DATE_ATOM, '2016-11-15T10:00:00+00:00'))
        ->withDateTo(DateTime::createFromFormat(DATE_ATOM, '2016-11-15T10:59:59+00:00'))
        ->withAffectedInverterId('Id12345.4')
        ->withReferenceInverterIds('Id12345.1,Id12345.2');

    $yieldLoss = new YieldLoss();
    $yieldLoss->realLostYield = 42.38;
    $yieldLoss->comment = 'New comment';

    $api->ticket(456)->yieldLosses()->referenceComponent()
        ->replace($referenceComponentCriteria, $yieldLoss);

Response

PUT tickets/<ticketId>/yield-losses/reference-component

Path parameters

Name	Type	Description
ticketId `required`	`integer`	Ticket ID

Query parameters

Name	Type	Description
from `required`	`date`ǀ`datetime`	Start date
to `required`	`date`ǀ`datetime`	End date
affectedInverterId `required`	`string`	Affected inverter ID
referenceInverterIds `required`	`string`	Reference inverter IDs (comma separated)

Request headers

Name	Type	Description
Content-Type `required`	`application/json`

Request body (JSON)

Property	Type	Description
realLostYield `required`	`number`ǀ`null`	Correction yield loss value
comment `required`	`string`ǀ`null`	Comment

Response

The response body is empty.

Http-Code: 204

Reference system

Calculate the yield loss using the reference system model

Request

curl 'https://api.meteocontrol.de/v2/tickets/456/yield-losses/reference-system?from=2016-11-15T10:00:00+00:00&to=2016-11-15T10:59:59+00:00&referenceSystemKey=ABCDE'

<?php
    $referenceSystemCriteria = (new ReferenceSystemCriteria())
        ->withDateFrom(DateTime::createFromFormat(DATE_ATOM, '2016-11-15T10:00:00+00:00'))
        ->withDateTo(DateTime::createFromFormat(DATE_ATOM, '2016-11-15T10:59:59+00:00'))
        ->withReferenceSystemKey('ABCDE');
    /** @var CalculationResult $calculationResult */
    $calculationResult = $api->ticket(456)->yieldLosses()->referenceSystem()
        ->get($referenceSystemCriteria);

Response

{
  "data":{
    "result": 69.32,
    "realLostYield": 41.29,
    "totalCompensation": 7.34962,
    "comment": ""
  }
}

<?php
    /** @var CalculationResult $calculationResult */
    echo $calculationResult->result;// 69.32
    echo $calculationResult->realLostYield;// 41.29
    echo $calculationResult->totalCompensation;// 7.34962
    echo $calculationResult->comment;// ""

GET tickets/<ticketId>/yield-losses/reference-system

Path parameters

Name	Type	Description
ticketId `required`	`integer`	Ticket ID

Query parameters

Name	Type	Description
from `required`	`date`ǀ`datetime`	Start date
to `required`	`date`ǀ`datetime`	End date
referenceSystemKey `required`	`string`	Reference system key

Response

CalculationResult object

Property	Type	Description
result `fixed`	`number`	Calculated yield loss value
realLostYield `fixed`	`number`	Correction yield loss value (if not specified, the value will be the same as `result`)
totalCompensation `fixed`	`number`	Estimation amount of the financial compensation (based on the value of `realLostYield`)
comment `fixed`	`string`	Comment

Calculate the yield loss using the reference system model and save the result

Will create a new record of the yield loss calculation result in the database or rewrite the record if one exists.

Request

curl -i -X PUT \
   -H 'Content-Type:application/json' \
   -d \
'{
  "realLostYield": 42.38,
  "comment": "New comment"
}' \ 
  'https://api.meteocontrol.de/v2/tickets/456/yield-losses/reference-system?from=2016-11-15T10:00:00+00:00&to=2016-11-15T10:59:59+00:00&referenceSystemKey=ABCDE'

<?php
    $referenceSystemCriteria = (new ReferenceSystemCriteria())
        ->withDateFrom(DateTime::createFromFormat(DATE_ATOM, '2016-11-15T10:00:00+00:00'))
        ->withDateTo(DateTime::createFromFormat(DATE_ATOM, '2016-11-15T10:59:59+00:00'))
        ->withReferenceSystemKey('ABCDE');

    $yieldLoss = new YieldLoss();
    $yieldLoss->realLostYield = 42.38;
    $yieldLoss->comment = 'New comment';

    $api->ticket(456)->yieldLosses()->referenceSystem()
        ->replace($referenceSystemCriteria, $yieldLoss);

Response

PUT tickets/<ticketId>/yield-losses/reference-system

Path parameters

Name	Type	Description
ticketId `required`	`integer`	Ticket ID

Query parameters

Name	Type	Description
from `required`	`date`ǀ`datetime`	Start date
to `required`	`date`ǀ`datetime`	End date
referenceSystemKey `required`	`string`	Reference system key

Request headers

Name	Type	Description
Content-Type `required`	`application/json`

Request body (JSON)

Property	Type	Description
realLostYield `required`	`number`ǀ`null`	Correction yield loss value
comment `required`	`string`ǀ`null`	Comment

Response

The response body is empty.

Http-Code: 204

Simplified peak (energy trader)

Calculate the yield loss using the simplified peak model with energy trader source data

Reference: Bundesnetzagentur (2020). 3.2.3.2 Vereinfachte Spitzabrechnung. In Bilanzierungsmodelle und Bestimmung der Ausfallarbeit (p. 9).

Request

curl 'https://api.meteocontrol.de/v2/tickets/45678/yield-losses/simplified-peak/energy-trader?from=2021-05-05T00:00:00+00:00&to=2021-05-10T23:59:59+00:00&resolution=900'

<?php
    $yieldLossesCriteria = (new YieldLossesCriteria())
        ->withDateFrom(DateTime::createFromFormat(DATE_ATOM, '2021-05-05T00:00:00+00:00'))
        ->withDateTo(DateTime::createFromFormat(DATE_ATOM, '2021-05-10T23:59:59+00:00'))
        ->withResolution(900);
    /** @var CalculationResult $calculationResult */
    $calculationResult = $api->ticket(45678)->yieldLosses()->simplifiedPeak()->energyTrader()
        ->get($yieldLossesCriteria);

Response

{
  "data":{
    "result": 69.32,
    "realLostYield": 41.29,
    "totalCompensation": 7.34962,
    "comment": ""
  }
}

<?php
    /** @var CalculationResult $calculationResult */
    echo $calculationResult->result;// 69.32
    echo $calculationResult->realLostYield;// 41.29
    echo $calculationResult->totalCompensation;// 7.34962
    echo $calculationResult->comment;// ""

GET tickets/<ticketId>/yield-losses/simplified-peak/energy-trader

Path parameters

Name	Type	Description
ticketId `required`	`integer`	Ticket ID

Query parameters

Name	Type	Description
from `required`	`date`ǀ`datetime`	Start date
to `required`	`date`ǀ`datetime`	End date
resolution `optional`	`integer`	Resolution in seconds¹

¹ Only 900 seconds is supported. Default resolution uses datalogger interval.

Response

CalculationResult object

Property	Type	Description
result `fixed`	`number`	Calculated yield loss value
realLostYield `fixed`	`number`	Correction yield loss value (if not specified, the value will be the same as `result`)
totalCompensation `fixed`	`number`	Estimation amount of the financial compensation (based on the value of `realLostYield`)
comment `fixed`	`string`	Comment

Calculate the yield loss using the simplified peak model with energy trader source data and save the result

Will create a new record of the yield loss calculation result in the database or rewrite the record if one exists.

Request

curl -i -X PUT \
   -H 'Content-Type:application/json' \
   -d \
'{
  "comment": "New comment"
}' \ 
  'https://api.meteocontrol.de/v2/tickets/45678/yield-losses/simplified-peak/energy-trader?from=2022-05-25T00:00:00+00:00&to=2022-05-31T23:59:59+00:00&resolution=900'

<?php
    $yieldLossesCriteria = (new YieldLossesCriteria())
        ->withDateFrom(DateTime::createFromFormat(DATE_ATOM, '2022-05-25T00:00:00+00:00'))
        ->withDateTo(DateTime::createFromFormat(DATE_ATOM, '2022-05-31T23:59:59+00:00'))
        ->withResolution(900);

    $yieldLoss = new YieldLoss();
    $yieldLoss->comment = 'New comment';

    $api->ticket(45678)->yieldLosses()->simplifiedPeak()->energyTrader()
        ->replace($yieldLossesCriteria, $yieldLoss);

Response

PUT tickets/<ticketId>/yield-losses/simplified-peak/energy-trader

Path parameters

Name	Type	Description
ticketId `required`	`integer`	Ticket ID

Query parameters

Name	Type	Description
from `required`	`date`ǀ`datetime`	Start date
to `required`	`date`ǀ`datetime`	End date
resolution `optional`	`integer`	Resolution in seconds¹

¹ Only 900 seconds is supported. Default resolution uses datalogger interval.

Request headers

Name	Type	Description
Content-Type `required`	`application/json`

Request body (JSON)

Property	Type	Description
comment `required`	`string`ǀ`null`	Comment

Response

The response body is empty.

Http-Code: 204

Simplified peak (grid operator)

Calculate the yield loss using the simplified peak model with grid operator source data

Reference: Bundesnetzagentur (2020). 3.2.3.2 Vereinfachte Spitzabrechnung. In Bilanzierungsmodelle und Bestimmung der Ausfallarbeit (p. 9).

Request

curl 'https://api.meteocontrol.de/v2/tickets/45678/yield-losses/simplified-peak/grid-operator?from=2022-05-25T00:00:00+00:00&to=2022-05-31T23:59:59+00:00'

<?php
    $yieldLossesCriteria = (new YieldLossesCriteria())
        ->withDateFrom(DateTime::createFromFormat(DATE_ATOM, '2022-05-25T00:00:00+00:00'))
        ->withDateTo(DateTime::createFromFormat(DATE_ATOM, '2022-05-31T23:59:59+00:00'));
    /** @var CalculationResult $calculationResult */
    $calculationResult = $api->ticket(45678)->yieldLosses()->simplifiedPeak()->gridOperator()
        ->get($yieldLossesCriteria);

Response

{
  "data":{
    "result": 69.32,
    "realLostYield": 41.29,
    "totalCompensation": 7.34962,
    "comment": ""
  }
}

<?php
    /** @var CalculationResult $calculationResult */
    echo $calculationResult->result;// 69.32
    echo $calculationResult->realLostYield;// 41.29
    echo $calculationResult->totalCompensation;// 7.34962
    echo $calculationResult->comment;// ""

GET tickets/<ticketId>/yield-losses/simplified-peak/grid-operator

Path parameters

Name	Type	Description
ticketId `required`	`integer`	Ticket ID

Query parameters

Name	Type	Description
from `required`	`date`ǀ`datetime`	Start date
to `required`	`date`ǀ`datetime`	End date

Response

CalculationResult object

Property	Type	Description
result `fixed`	`number`	Calculated yield loss value
realLostYield `fixed`	`number`	Correction yield loss value (if not specified, the value will be the same as `result`)
totalCompensation `fixed`	`number`	Estimation amount of the financial compensation (based on the value of `realLostYield`)
comment `fixed`	`string`	Comment

Calculate the yield loss using the simplified peak model with grid operator source data and save the result

Will create a new record of the yield loss calculation result in the database or rewrite the record if one exists.

Request

curl -i -X PUT \
   -H 'Content-Type:application/json' \
   -d \
'{
  "comment": "New comment"
}' \ 
  'https://api.meteocontrol.de/v2/tickets/45678/yield-losses/simplified-peak/grid-operator?from=2022-05-25T00:00:00+00:00&to=2022-05-31T23:59:59+00:00'

<?php
    $yieldLossesCriteria = (new YieldLossesCriteria())
        ->withDateFrom(DateTime::createFromFormat(DATE_ATOM, '2022-05-25T00:00:00+00:00'))
        ->withDateTo(DateTime::createFromFormat(DATE_ATOM, '2022-05-31T23:59:59+00:00'));

    $yieldLoss = new YieldLoss();
    $yieldLoss->comment = 'New comment';

    $api->ticket(45678)->yieldLosses()->simplifiedPeak()->gridOperator()
        ->replace($yieldLossesCriteria, $yieldLoss);

Response

PUT tickets/<ticketId>/yield-losses/simplified-peak/grid-operator

Path parameters

Name	Type	Description
ticketId `required`	`integer`	Ticket ID

Query parameters

Name	Type	Description
from `required`	`date`ǀ`datetime`	Start date
to `required`	`date`ǀ`datetime`	End date

Request headers

Name	Type	Description
Content-Type `required`	`application/json`

Request body (JSON)

Property	Type	Description
comment `required`	`string`ǀ`null`	Comment

Response

The response body is empty.

Http-Code: 204

Simplified peak (manual)

Calculate the yield loss using the simplified peak model with manual source data

Reference: Bundesnetzagentur (2020). 3.2.3.2 Vereinfachte Spitzabrechnung. In Bilanzierungsmodelle und Bestimmung der Ausfallarbeit (p. 9).

Request

curl 'https://api.meteocontrol.de/v2/tickets/45678/yield-losses/simplified-peak/manual?from=2022-05-25T00:00:00+00:00&to=2022-05-31T23:59:59+00:00'

<?php
    $yieldLossesCriteria = (new YieldLossesCriteria())
        ->withDateFrom(DateTime::createFromFormat(DATE_ATOM, '2022-05-25T00:00:00+00:00'))
        ->withDateTo(DateTime::createFromFormat(DATE_ATOM, '2022-05-31T23:59:59+00:00'));
    /** @var CalculationResult $calculationResult */
    $calculationResult = $api->ticket(45678)->yieldLosses()->simplifiedPeak()->manual()
        ->get($yieldLossesCriteria);

Response

{
  "data":{
    "result": 69.32,
    "realLostYield": 41.29,
    "totalCompensation": 7.34962,
    "comment": ""
  }
}

<?php
    /** @var CalculationResult $calculationResult */
    echo $calculationResult->result;// 69.32
    echo $calculationResult->realLostYield;// 41.29
    echo $calculationResult->totalCompensation;// 7.34962
    echo $calculationResult->comment;// ""

GET tickets/<ticketId>/yield-losses/simplified-peak/manual

Path parameters

Name	Type	Description
ticketId `required`	`integer`	Ticket ID

Query parameters

Name	Type	Description
from `required`	`date`ǀ`datetime`	Start date
to `required`	`date`ǀ`datetime`	End date

Response

CalculationResult object

Property	Type	Description
result `fixed`	`number`	Calculated yield loss value
realLostYield `fixed`	`number`	Correction yield loss value (if not specified, the value will be the same as `result`)
totalCompensation `fixed`	`number`	Estimation amount of the financial compensation (based on the value of `realLostYield`)
comment `fixed`	`string`	Comment

Calculate the yield loss using the simplified peak model with manual source data and save the result

Will create a new record of the yield loss calculation result in the database or rewrite the record if one exists.

Request

curl -i -X PUT \
   -H 'Content-Type:application/json' \
   -d \
'{
  "comment": "New comment"
}' \ 
  'https://api.meteocontrol.de/v2/tickets/45678/yield-losses/simplified-peak/manual?from=2022-05-25T00:00:00+00:00&to=2022-05-31T23:59:59+00:00'

<?php
    $yieldLossesCriteria = (new YieldLossesCriteria())
        ->withDateFrom(DateTime::createFromFormat(DATE_ATOM, '2022-05-25T00:00:00+00:00'))
        ->withDateTo(DateTime::createFromFormat(DATE_ATOM, '2022-05-31T23:59:59+00:00'));

    $yieldLoss = new YieldLoss();
    $yieldLoss->comment = 'New comment';

    $api->ticket(45678)->yieldLosses()->simplifiedPeak()->manual()
        ->replace($yieldLossesCriteria, $yieldLoss);

Response

PUT tickets/<ticketId>/yield-losses/simplified-peak/manual

Path parameters

Name	Type	Description
ticketId `required`	`integer`	Ticket ID

Query parameters

Name	Type	Description
from `required`	`date`ǀ`datetime`	Start date
to `required`	`date`ǀ`datetime`	End date

Request headers

Name	Type	Description
Content-Type `required`	`application/json`

Request body (JSON)

Property	Type	Description
comment `required`	`string`ǀ`null`	Comment

Response

The response body is empty.

Http-Code: 204

Simplified peak (static)

Calculate the yield loss using the simplified peak model with static source data

Reference: Bundesnetzagentur (2020). 3.2.3.2 Vereinfachte Spitzabrechnung. In Bilanzierungsmodelle und Bestimmung der Ausfallarbeit (p. 9).

Request

curl 'https://api.meteocontrol.de/v2/tickets/45678/yield-losses/simplified-peak/static?from=2022-05-25T00:00:00+00:00&to=2022-05-31T23:59:59+00:00'

<?php
    $yieldLossesCriteria = (new YieldLossesCriteria())
        ->withDateFrom(DateTime::createFromFormat(DATE_ATOM, '2022-05-25T00:00:00+00:00'))
        ->withDateTo(DateTime::createFromFormat(DATE_ATOM, '2022-05-31T23:59:59+00:00'));
    /** @var CalculationResult $calculationResult */
    $calculationResult = $api->ticket(45678)->yieldLosses()->simplifiedPeak()->static()
        ->get($yieldLossesCriteria);

Response

{
  "data":{
    "result": 69.32,
    "realLostYield": 41.29,
    "totalCompensation": 7.34962,
    "comment": ""
  }
}

<?php
    /** @var CalculationResult $calculationResult */
    echo $calculationResult->result;// 69.32
    echo $calculationResult->realLostYield;// 41.29
    echo $calculationResult->totalCompensation;// 7.34962
    echo $calculationResult->comment;// ""

GET tickets/<ticketId>/yield-losses/simplified-peak/static

Path parameters

Name	Type	Description
ticketId `required`	`integer`	Ticket ID

Query parameters

Name	Type	Description
from `required`	`date`ǀ`datetime`	Start date
to `required`	`date`ǀ`datetime`	End date

Response

CalculationResult object

Property	Type	Description
result `fixed`	`number`	Calculated yield loss value
realLostYield `fixed`	`number`	Correction yield loss value (if not specified, the value will be the same as `result`)
totalCompensation `fixed`	`number`	Estimation amount of the financial compensation (based on the value of `realLostYield`)
comment `fixed`	`string`	Comment

Calculate the yield loss using the simplified peak model with static source data and save the result

Will create a new record of the yield loss calculation result in the database or rewrite the record if one exists.

Request

curl -i -X PUT \
   -H 'Content-Type:application/json' \
   -d \
'{
  "comment": "New comment"
}' \ 
  'https://api.meteocontrol.de/v2/tickets/45678/yield-losses/simplified-peak/static?from=2022-05-25T00:00:00+00:00&to=2022-05-31T23:59:59+00:00'

<?php
    $yieldLossesCriteria = (new YieldLossesCriteria())
        ->withDateFrom(DateTime::createFromFormat(DATE_ATOM, '2022-05-25T00:00:00+00:00'))
        ->withDateTo(DateTime::createFromFormat(DATE_ATOM, '2022-05-31T23:59:59+00:00'));

    $yieldLoss = new YieldLoss();
    $yieldLoss->comment = 'New comment';

    $api->ticket(45678)->yieldLosses()->simplifiedPeak()->static()
        ->replace($yieldLossesCriteria, $yieldLoss);

Response

PUT tickets/<ticketId>/yield-losses/simplified-peak/static

Path parameters

Name	Type	Description
ticketId `required`	`integer`	Ticket ID

Query parameters

Name	Type	Description
from `required`	`date`ǀ`datetime`	Start date
to `required`	`date`ǀ`datetime`	End date

Request headers

Name	Type	Description
Content-Type `required`	`application/json`

Request body (JSON)

Property	Type	Description
comment `required`	`string`ǀ`null`	Comment

Response

The response body is empty.

Http-Code: 204

Simplified peak (undetermined)

Calculate the yield loss using the simplified peak model with undetermined source data

Reference: Bundesnetzagentur (2020). 3.2.3.2 Vereinfachte Spitzabrechnung. In Bilanzierungsmodelle und Bestimmung der Ausfallarbeit (p. 9).

Request

curl 'https://api.meteocontrol.de/v2/tickets/56789/yield-losses/simplified-peak/undetermined?from=2025-07-01T00:00:00+00:00&to=2025-07-01T23:59:59+00:00'

<?php
    $yieldLossesCriteria = (new YieldLossesCriteria())
        ->withDateFrom(DateTime::createFromFormat(DATE_ATOM, '2025-07-01T00:00:00+00:00'))
        ->withDateTo(DateTime::createFromFormat(DATE_ATOM, '2025-07-01T23:59:59+00:00'));
    /** @var CalculationResult $calculationResult */
    $calculationResult = $api->ticket(56789)->yieldLosses()->simplifiedPeak()->undetermined()
        ->get($yieldLossesCriteria);

Response

{
  "data":{
    "result": 69.32,
    "realLostYield": 41.29,
    "totalCompensation": 7.34962,
    "comment": ""
  }
}

<?php
    /** @var CalculationResult $calculationResult */
    echo $calculationResult->result;// 69.32
    echo $calculationResult->realLostYield;// 41.29
    echo $calculationResult->totalCompensation;// 7.34962
    echo $calculationResult->comment;// ""

GET tickets/<ticketId>/yield-losses/simplified-peak/undetermined

Path parameters

Name	Type	Description
ticketId `required`	`integer`	Ticket ID

Query parameters

Name	Type	Description
from `required`	`date`ǀ`datetime`	Start date
to `required`	`date`ǀ`datetime`	End date

Response

CalculationResult object

Property	Type	Description
result `fixed`	`number`	Calculated yield loss value
realLostYield `fixed`	`number`	Correction yield loss value (if not specified, the value will be the same as `result`)
totalCompensation `fixed`	`number`	Estimation amount of the financial compensation (based on the value of `realLostYield`)
comment `fixed`	`string`	Comment

Calculate the yield loss using the simplified peak model with undetermined source data and save the result

Will create a new record of the yield loss calculation result in the database or rewrite the record if one exists.

Request

curl -i -X PUT \
   -H 'Content-Type:application/json' \
   -d \
'{
  "comment": "New comment"
}' \ 
  'https://api.meteocontrol.de/v2/tickets/56789/yield-losses/simplified-peak/undetermined?from=2025-07-01T00:00:00+00:00&to=2025-07-01T23:59:59+00:00'

<?php
    $yieldLossesCriteria = (new YieldLossesCriteria())
        ->withDateFrom(DateTime::createFromFormat(DATE_ATOM, '2025-07-01T00:00:00+00:00'))
        ->withDateTo(DateTime::createFromFormat(DATE_ATOM, '2025-07-01T23:59:59+00:00'));

    $yieldLoss = new YieldLoss();
    $yieldLoss->comment = 'New comment';

    $api->ticket(56789)->yieldLosses()->simplifiedPeak()->undetermined()
        ->replace($yieldLossesCriteria, $yieldLoss);

Response

PUT tickets/<ticketId>/yield-losses/simplified-peak/undetermined

Path parameters

Name	Type	Description
ticketId `required`	`integer`	Ticket ID

Query parameters

Name	Type	Description
from `required`	`date`ǀ`datetime`	Start date
to `required`	`date`ǀ`datetime`	End date

Request headers

Name	Type	Description
Content-Type `required`	`application/json`

Request body (JSON)

Property	Type	Description
comment `required`	`string`ǀ`null`	Comment

Response

The response body is empty.

Http-Code: 204

Simulation

Calculate the yield loss using the simulation model

Request

curl 'https://api.meteocontrol.de/v2/tickets/456/yield-losses/simulation?from=2016-11-15T10:00:00+00:00&to=2016-11-15T10:59:59+00:00'

<?php
    $yieldLossesCriteria = (new YieldLossesCriteria())
        ->withDateFrom(DateTime::createFromFormat(DATE_ATOM, '2016-11-15T10:00:00+00:00'))
        ->withDateTo(DateTime::createFromFormat(DATE_ATOM, '2016-11-15T10:59:59+00:00'));
    /** @var CalculationResult $calculationResult */
    $calculationResult = $api->ticket(456)->yieldLosses()->simulation()
        ->get($yieldLossesCriteria);

Response

{
  "data": {
    "result": 69.32,
    "realLostYield": 41.29,
    "totalCompensation": 7.34962,
    "comment": ""
  }
}

<?php
    /** @var CalculationResult $calculationResult */
    echo $calculationResult->result;// 69.32
    echo $calculationResult->realLostYield;// 41.29
    echo $calculationResult->totalCompensation;// 7.34962
    echo $calculationResult->comment;// ""

GET tickets/<ticketId>/yield-losses/simulation

Path parameters

Name	Type	Description
ticketId `required`	`integer`	Ticket ID

Query parameters

Name	Type	Description
from `required`	`date`ǀ`datetime`	Start date
to `required`	`date`ǀ`datetime`	End date

Response

CalculationResult object

Property	Type	Description
result `fixed`	`number`	Calculated yield loss value
realLostYield `fixed`	`number`	Correction yield loss value (if not specified, the value will be the same as `result`)
totalCompensation `fixed`	`number`	Estimation amount of the financial compensation (based on the value of `realLostYield`)
comment `fixed`	`string`	Comment

Calculate the yield loss using the simulation model and save the result

Will create a new record of the yield loss calculation result in the database or rewrite the record if one exists.

Request

curl -i -X PUT \
   -H 'Content-Type:application/json' \
   -d \
'{
  "realLostYield": 42.38,
  "comment": "New comment"
}' \ 
  'https://api.meteocontrol.de/v2/tickets/456/yield-losses/simulation?from=2016-11-15T10:00:00+00:00&to=2016-11-15T10:59:59+00:00'

<?php
    $yieldLossesCriteria = (new YieldLossesCriteria())
        ->withDateFrom(DateTime::createFromFormat(DATE_ATOM, '2016-11-15T10:00:00+00:00'))
        ->withDateTo(DateTime::createFromFormat(DATE_ATOM, '2016-11-15T10:59:59+00:00'));

    $yieldLoss = new YieldLoss();
    $yieldLoss->realLostYield = 42.38;
    $yieldLoss->comment = 'New comment';

    $api->ticket(456)->yieldLosses()->simulation()
        ->replace($yieldLossesCriteria, $yieldLoss);

Response

PUT tickets/<ticketId>/yield-losses/simulation

Path parameters

Name	Type	Description
ticketId `required`	`integer`	Ticket ID

Query parameters

Name	Type	Description
from `required`	`date`ǀ`datetime`	Start date
to `required`	`date`ǀ`datetime`	End date

Request headers

Name	Type	Description
Content-Type `required`	`application/json`

Request body (JSON)

Property	Type	Description
realLostYield `required`	`number`ǀ`null`	Correction yield loss value
comment `required`	`string`ǀ`null`	Comment

Response

The response body is empty.

Http-Code: 204

CMMS

This API is currently in Beta status and may change before the final release

Access to the CMMS endpoints requires to have VCOM CMMS activated. Please contact our sales department if you are interested.

Systems

Get all CMMS systems

Request

curl 'https://api.meteocontrol.de/v2/cmms/systems'

<?php
    /** @var CmmsSystem[] $cmmsSystems */
    $cmmsSystems = $api->cmms()->systems()->get();

Response

{
  "data": [
    {
      "key": "ABCDE",
      "name": "PV system",
      "renew": 1,
      "activeUntil": "2021-12-31",
      "activeSince": "2020-01-01"
    }
  ]
}

<?php
    /** @var CmmsSystem[] $cmmsSystems */
    echo $cmmsSystems[0]->key;// ABCDE
    echo $cmmsSystems[0]->name;// PV system
    echo $cmmsSystems[0]->renew;// 1
    echo $cmmsSystems[0]->activeUntil->format('Y-m-d');// 2021-12-31
    echo $cmmsSystems[0]->activeSince->format('Y-m-d');// 2020-01-01

GET systems

Returns an array of CmmsSystem objects.

Response

CmmsSystem object

Property	Type	Description
key `fixed`	`string`	Identification key of the system
name `fixed`	`string`	System name
renew `fixed`	(`0`ǀ`1`ǀ`null`)	Renew state
activeUntil `fixed`	`datetime`ǀ`null`	License active until date
activeSince `fixed`	`datetime`ǀ`null`	License active since date

Site access

Get CMMS site access

Request

curl 'https://api.meteocontrol.de/v2/cmms/site-access?systemKey=ABCDE&status=unregistered'

<?php
    $siteAccessCriteria = (new SiteAccessCriteria())
        ->withSystemKey("ABCDE")
        ->withStatus(SiteAccess::STATUS_UNREGISTERED);
    /** @var SiteAccess[] $siteAccess */
    $siteAccess = $api->cmms()->siteAccess()->get($siteAccessCriteria);

Response

{
  "data": [
    {
      "system": {
        "key": "ABCDE",
        "name": "System name"
      },
      "name": "Site access name",
      "status": "unregistered",
      "comment": "Access comment",
      "checkIn": "2025-04-10 11:06:09",
      "checkOut": "2025-04-10 12:30:20"
    }
  ]
}

<?php
    /** @var SiteAccess[] $siteAccess */
    echo $siteAccess[0]->system->key;// ABCDE
    echo $siteAccess[0]->system->name;// System name
    echo $siteAccess[0]->name;// Site access name
    echo $siteAccess[0]->status;// unregistered
    echo $siteAccess[0]->comment;// Access comment
    echo $siteAccess[0]->checkIn->format('Y-m-d H:i:s');// 2025-04-10 11:06:09
    echo $siteAccess[0]->checkOut->format('Y-m-d H:i:s');// 2025-04-10 12:30:20

GET site-access

Returns an array of SiteAccess objects.

Query parameters

Name	Type	Description
systemKey `optional`	`string`	Can contain comma delimited system keys
status `optional`	(`unregistered`ǀ`registered`ǀ`exceeded`)	Can contain comma delimited status
checkIn `optional`	`datetime`	Check in date (Greater than or equal)
checkOut `optional`	`datetime`	Check out date (Less than or equal)

Response

Only the 500 last check in entries will be returned.

SiteAccess object

Property	Type	Description
system `fixed`	`System`	System information
name `fixed`	`string`	Site access name
status `fixed`	(`unregistered`ǀ`registered`ǀ`exceeded`)	Site access state
comment `fixed`	`string`ǀ`null`	Comment
checkIn `fixed`	`datetime`	Check in date
checkOut `fixed`	`datetime`ǀ`null`	Check out date

System object

Property	Type	Description
key `fixed`	`string`	Identification key of the system
name `fixed`	`string`	System name

Work orders

Get all work orders

Request

curl 'https://api.meteocontrol.de/v2/cmms/workorders?systemKey=ABCDE'

<?php
    $systemCriteria = (new SystemCriteria())
        ->withSystemKey('ABCDE');
    /** @var WorkOrder[] $workOrders */
    $cmmsSystems = $api->cmms()->workOrders()->get($systemCriteria);

Response

{
  "data": [
    {
      "workOrderId": 123,
      "title": "work order title",
      "lastChangedAt": "2020-08-12T00:00:00+00:00"
    }
  ]
}

<?php
    /** @var WorkOrder[] $workOrders */
    echo $workOrders[0]->workOrderId;// 123
    echo $workOrders[0]->title;// work order title
    echo $workOrders[0]->lastChangedAt->format(DATE_ATOM);// 2020-08-12T00:00:00+00:00

GET workorders

Returns an array of work order objects.

Query parameters

Name	Type	Description
systemKey `optional`	`string`	Identification key of the system

Response

WorkOrder object

Property	Type	Description
workOrderId `fixed`	`integer`	Work order ID
title `fixed`	`string`	Work order title
lastChangedAt `fixed`	`datetime`ǀ`null`	Last change timestamp in UTC timezone

Get single work order

Request

curl 'https://api.meteocontrol.de/v2/cmms/workorders/123'

<?php
    /** @var WorkOrderDetail $workOrder */
    $workOrder = $api->cmms()->workOrder(123)->get();

Response

{
  "data": {
    "workOrderId": 123,
    "ticketId": 12345,
    "systemKey": "ABCDE",
    "title": "work order title",
    "description": "work order description",
    "status": "processed",
    "dueAt": "2021-07-08T00:00:00+00:00",
    "dueDate": "2021-07-08",
    "createdAt": "2020-07-08T06:39:58+00:00",
    "completedAt": null,
    "lastChangedAt": "2020-08-12T00:00:00+00:00",
    "assignee": {
      "username": "user-name",
      "status": "accepted",
      "statusDateAt": "2020-08-12T00:00:00+00:00",
      "statusReason": null
    }
  }
}

<?php
    /** @var WorkOrderDetail[] $workOrder */
    echo $workOrder->workOrderId;// 123
    echo $workOrder->ticketId;// 12345
    echo $workOrder->systemKey;// ABCDE
    echo $workOrder->title;// work order title
    echo $workOrder->description;// work order description
    echo $workOrder->status;// processed
    echo $workOrder->dueAt->format(DATE_ATOM);// 2021-07-08T00:00:00+00:00
    echo $workOrder->dueDate->format('Y-m-d');// 2021-07-08
    echo $workOrder->createdAt->format(DATE_ATOM);// 2020-07-08T06:39:58+00:00
    echo $workOrder->lastChangedAt->format(DATE_ATOM);// 2020-08-12T00:00:00+00:00
    echo $workOrder->assignee->username;// user-name
    echo $workOrder->assignee->status;// accepted
    echo $workOrder->assignee->statusDateAt->format(DATE_ATOM);// 2020-08-12T00:00:00+00:00
    echo $workOrder->assignee->statusReason;// null

GET workorders/<workOrderId>

Path parameters

Name	Type	Description
workOrderId `required`	`integer`	Work order ID

Response

WorkOrderDetail object

Property	Type	Description
workOrderId `fixed`	`integer`	Work order ID
ticketId `fixed`	`integer`	Ticket ID
systemKey `fixed`	`string`	Identification key of the system
title `fixed`	`string`	Work order title
description `fixed`	`string`	Work order description
status `fixed`	(`closed`ǀ`declined`ǀ`inProgress`ǀ`open`ǀ`processed`)	Work order status
dueAt `fixed`	`string`	Work order due date (deprecated)
dueDate `fixed`	`string`	Work order due date
createdAt `fixed`	`datetime`	Created timestamp in UTC timezone
lastChangedAt `fixed`	`datetime`ǀ`null`	Last change timestamp in UTC timezone
assignee `fixed`	`array`	username `string`, status `string`, statusDateAt `datetime`, statusReason `string`

Forms

Get all work order forms

Request

curl 'https://api.meteocontrol.de/v2/cmms/workorders/123/forms'

<?php
    /** @var WorkOrderForm[] $forms */
    $forms = $api->cmms()->workOrder(123)->forms()->get();

Response

{
  "data": [
    {
      "formId": 456,
      "title": "form title",
      "lastChangedAt": "2020-10-22T00:00:00+00:00"
    }
  ]
}

<?php
    /** @var WorkOrderForm[] $forms */
    echo $forms[0]->formId;// 456
    echo $forms[0]->title;// form title
    echo $forms[0]->lastChangedAt->format(DATE_ATOM);// 2020-10-22T00:00:00+00:00

GET workorders/<workOrderId>/forms

Returns an array of work order form objects.

Path parameters

Name	Type	Description
workOrderId `required`	`integer`	Work order ID

Response

WorkOrderForm object

Property	Type	Description
formId `fixed`	`integer`	Form ID
title `fixed`	`string`	Form title
lastChangedAt `fixed`	`datetime`ǀ`null`	Last change timestamp in UTC timezone

Get single work order form

Request

curl 'https://api.meteocontrol.de/v2/cmms/workorders/123/forms/456'

<?php
    /** @var WorkOrderFormDetail $form */
    $form = $api->cmms()->workOrder(123)->form(456)->get();

Response

{
  "data": {
    "formId": 456,
    "workOrderId": 123,
    "title": "form title",
    "description": "form description",
    "form": "{\"elements\":[{\"label\":\"Erste Seite\",\"component\":\"page\"}]}",
    "data": "{}",
    "originalData": null,
    "savedAt": "2020-05-18T13:14:45+00:00",
    "createdAt": "2020-05-18T13:14:45+00:00",
    "completedAt": "2020-10-22T00:00:00+00:00",
    "lastChangedAt": "2020-10-22T00:00:00+00:00",
    "completedBy": "user-name",
    "changedBy": "user-name",
    "editable": false
  }
}

<?php
    /** @var WorkOrderFormDetail[] $form */
    echo $form->formId;// 456
    echo $form->workOrderId;// 123
    echo $form->title;// form title
    echo $form->description;// form description
    echo $form->form;// {"elements":[{"label":"Erste Seite","component":"page"}]}
    echo $form->data;// {}
    echo $form->originalData;// null
    echo $form->savedAt->format(DATE_ATOM);// 2020-05-18T13:14:45+00:00
    echo $form->createdAt->format(DATE_ATOM);// 2020-05-18T13:14:45+00:00
    echo $form->completedAt->format(DATE_ATOM);// 2020-10-22T00:00:00+00:00
    echo $form->lastChangedAt->format(DATE_ATOM);// 2020-10-22T00:00:00+00:00
    echo $form->completedBy;// user-name
    echo $form->changedBy;// user-name
    echo $form->editable;// false

GET workorders/<workOrderId>/forms/<formId>

Path parameters

Name	Type	Description
workOrderId `required`	`integer`	Work order ID
formId `required`	`integer`	Form ID

Response

WorkOrderFormDetail object

Property	Type	Description
formId `fixed`	`integer`	Form ID
workOrderId `fixed`	`integer`	Work order ID
title `fixed`	`string`	Form title
description `fixed`	`string`	Form description
form `fixed`	`string`	Form pattern
data `fixed`	`string`	Form data in JSON format
originalData `fixed`	`string`	Original data in JSON format
savedAt `fixed`	`datetime`ǀ`null`	Saved timestamp in UTC timezone
createdAt `fixed`	`datetime`	Created timestamp in UTC timezone
completedAt `fixed`	`datetime`ǀ`null`	Completed timestamp in UTC timezone
lastChangedAt `fixed`	`datetime`ǀ`null`	Last change timestamp in UTC timezone
completedBy `fixed`	`string`ǀ`null`	Completed by user
changedBy `fixed`	`string`ǀ`null`	Changed by user
editable `fixed`	`bool`	Form editable

Alarms

Types

Alarm types

Type	Description
`total-outage`	System or inverter total outage
`data-outage`	Component delivers no data
`communication-outage`	System or datalogger-wide communication problem
`misproduction`	System or inverter under-performing
`string-outage`	One or more strings of stringbox in outage
`sensor-outage`	Strange behaviour of irradiance sensor detected
`battery-charge-level`	Battery state of charge not within a user-configurable range
`custom`	Custom alarm configured by a user

Component types

Type	Description
`system`	Whole system or value on system level affected
`subsystem`	Substation (currently unused)
`datalogger`	Only used for communication issues
`inverter`
`sensor`
`meter`
`ppc`
`battery`
`tracker`
`stringbox`
`status`
`genset`

AlarmClosureInfo

Property	Type	Description
`userName`	`string`ǀ`null`	The user who closed the alarm, auto-closed if it is `null`
`comment`	`string`ǀ`null`	Closed comment from user

Objects

Component

Property	Type	Description
id `fixed`	`string`
type `fixed`	ComponentType
name `fixed`	`string`

Alarm

Property	Type	Description
id `fixed`	`integer`
alarmType `fixed`	AlarmType
component `fixed`	Component
systemKey `fixed`	`string`	Identification key of the system
ticketId `fixed`	`number`ǀ`null`	Id of assigned ticket, `null` if not assigned to a ticket
createdAt `fixed`	`datetime`	Created date in system timezone
lastChangedAt `fixed`	`datetime`	Last change date in system timezone
startedAt `fixed`	`datetime`	Started date in system timezone
status `fixed`	(`open`ǀ`closed`)
severity `fixed`	(`normal`ǀ`high`ǀ`critical`)
duration `fixed`	`string`	ISO-8601 duration
affectedPower `fixed`	`number`	In percent of installed system power, 0 if not applicable
losses `fixed`	`number`ǀ`null`	Estimated losses due to alarm in kWh, `null` if unavailable
closedAt `fixed`	`datetime`ǀ`null`	Closed datetime
closedBy `fixed`	AlarmClosureInfoǀ`null`	Information regarding how was the alarm been closed

Get all alarms

Request

curl 'https://api.meteocontrol.de/v2/alarms?
severity=high,critical&status=open&systemKey=ABCDE
&lastChangedAt[from]=2022-04-01T00:00:00+02:00
&lastChangedAt[to]=2022-04-30T23:59:59+02:00
&startedAt[from]=2022-04-01T00:00:00+02:00
&startedAt[to]=2022-04-30T23:59:59+02:00'

<?php
    $criteria = (new AlarmsCriteria())
        ->withSystemKey("ABCDE")
        ->withSeverity(Alarm::SEVERITY_HIGH)
        ->withSeverity(Alarm::SEVERITY_CRITICAL)
        ->withStatus(Alarm::STATUS_OPEN)
        ->withLastChangedAtFrom(new DateTime("2022-04-01T00:00:00+02:00"))
        ->withLastChangedAtTo(new DateTime("2022-04-30T23:59:59+02:00"))
        ->withStartedAtFrom(new DateTime("2022-04-01T00:00:00+02:00"))
        ->withStartedAtTo(new DateTime("2022-04-30T23:59:59+02:00"));
    /** @var Alarm[] $alarms */
    $alarms = $api->alarms()->find($criteria);

Response

{
  "data": [
    {
      "id": 123,
      "systemKey": "ABCDE",
      "ticketId": null,
      "alarmType": "misproduction",
      "component": {
          "id": "Id123.1",
          "type": "inverter",
          "name": "Inverter 1"
      },
      "createdAt": "2022-04-01T015:35:00+02:00",
      "lastChangedAt": "2022-04-10T09:15:00+02:00",
      "startedAt": "2022-04-01T015:35:00+02:00",
      "status": "open",
      "severity": "high",
      "duration": "PT300S",
      "affectedPower": 20.0,
      "losses": 12.4,
      "closedAt": null,
      "closedBy": null
    },
    {
      "id": 456,
      "systemKey": "ABCDE",
      "ticketId": null,
      "alarmType": "sensor-outage",
      "component": {
          "id": "ABCDE",
          "type": "system",
          "name": "Testsystem"
      },
      "createdAt": "2022-04-03T07:50:00+02:00",
      "lastChangedAt": "2022-04-03T09:50:00+02:00",
      "startedAt": "2022-04-03T07:50:00+02:00",
      "status": "open",
      "severity": "critical",
      "duration": "PT6H",
      "affectedPower": 0.0,
      "losses": null,
      "closedAt": null,
      "closedBy": null
    }
  ]
}

GET alarms

Query parameters

Name	Type	Description
ticketId `optional`	`integer`	Can contain comma delimited ticket ids
alarmType `optional`	AlarmType	Can contain comma delimited alarm types
componentType `optional`	Component	Can contain comma delimited component types
lastChangedAt[from] `optional`	`datetime`	Start date
lastChangedAt[to] `optional`	`datetime`	End date
createdAt[from] `optional`	`datetime`	Start date
createdAt[to] `optional`	`datetime`	End date
startedAt[from] `optional`	`datetime`	Start date
startedAt[to] `optional`	`datetime`	End date
status `optional`	(`open`ǀ`closed`)	Can contain comma delimited status, defaults to `open` if not specified
severity `optional`	(`normal`ǀ`high`ǀ`critical`)	Can contain comma delimited severity types
systemKey `optional`	`string`	Can contain comma delimited system keys

Response

A list of Alarm objects. Only the 1000 last updated entries will be returned.

Get single alarm

Request

curl 'https://api.meteocontrol.de/v2/alarms/789'

<?php
    /** @var Alarm $alarm */
    $alarm = $api->alarm(789)->get();

Response

{
  "data": {
    "id": 789,
    "systemKey": "ABCDE",
    "ticketId": null,
    "alarmType": "total-outage",
    "component": {
        "id": "ABCDE",
        "type": "system",
        "name": "Testsystem"
    },
    "createdAt": "2016-01-01T12:00:00+02:00",
    "lastChangedAt": "2016-01-01T13:00:00+02:00",
    "startedAt": "2016-01-01T12:00:00+02:00",
    "status": "closed",
    "severity": "critical",
    "duration": "PT1H",
    "affectedPower": 100.0,
    "losses": 28.3,
    "closedAt": "2016-01-01T13:00:00+02:00",
    "closedBy": {
      "userName": "user-name",
      "comment": "comment"
    }
  }
}

GET alarms/<alarmId>

Path parameters

Name	Type	Description
alarmId `required`	`integer`	Alarm ID

Response

A single Alarm object

Update single alarm

Request

curl -i -X PATCH \
   -H "Content-Type:application/json" \
   -d \
'{
  "ticketId": 12345
}' \
 'https://api.meteocontrol.de/v2/alarms/789'

<?php
    $alarm = new Alarm();
    $alarm->ticketId = 12345;
    $api->alarm(789)->update($alarm);

Response

PATCH alarms/<alarmId>

Path parameters

Name	Type	Description
alarmId `required`	`integer`	Alarm ID

Request headers

Name	Type	Description
Content-Type `required`	`application/json`

Request body (JSON)

Name	Type	Description
ticketId `required`	`integer`ǀ`null`	Ticket ID

Response

Status code	Description
`204`	If the alarm has updated
`403`	User is not authorized to access alarm

Close single alarm

Request

curl -i -X POST \
   -d \
 'https://api.meteocontrol.de/v2/alarms/789/close'

<?php
    $api->alarm(789)->close();

Response

POST alarms/<alarmId>

Path parameters

Name	Type	Description
alarmId `required`	`integer`	Alarm ID

Response

Status code	Description
`204`	If the alarm has set to close
`403`	User is not authorized to access alarm

OAuth Authentication

Request

# To get a new access token by password grant
curl -X POST \
   https://api.meteocontrol.de/v2/login \ 
   -H 'content-type: application/x-www-form-urlencoded' \
   -H 'x-api-key: <apiKey>' \
   -d 'grant_type=password' \
   -d 'username=vcomUsername' \
   -d 'password=strongPassword' \
   -d 'client_id=vcom-api' \
   -d 'client_secret=AYB=~9_f-BvNoLt8+x=3maCq)>/?@Nom'

# To get a new access token by refresh token grant
curl -X POST \
   https://api.meteocontrol.de/v2/login \ 
   -H 'content-type: application/x-www-form-urlencoded' \
   -H 'x-api-key: <apiKey>' \
   -d 'grant_type=refresh_token' \
   -d 'refresh_token=yourOldRefreshToken' \
   -d 'client_id=vcom-api' \
   -d 'client_secret=AYB=~9_f-BvNoLt8+x=3maCq)>/?@Nom'

The vcom-api-client handles token retrieving and refreshing for you automatically.

Response

{
    "token_type": "Bearer",
    "expires_in": 518400,
    "access_token": "yourAccessToken",
    "refresh_token": "yourRefreshToken"
}

The vcom-api-client handles token retrieving and refreshing for you automatically.

POST login

Body (Form) parameters

Name	Type	Description
grant_type `required`	`string`	(`password`ǀ`refresh_token`)
client_id `required`	`string`	The client ID: `vcom-api`
client_secret `required`	`string`	The client secret: `AYB=~9_f-BvNoLt8+x=3maCq)>/?@Nom`
username `required`	`string`	Your username to login VCOM
password `required`	`string`	Your password to login VCOM

Request number limitation

OAuth Token retrieval and refreshing is also subject to rate limiting, please re-use your access token.

Interval	Limitation
1 Minute	10
1 Day	7200

Every response contains the current rate limit in its headers:

Header field name	Description
X-RateLimit-Reset-Minute	The time at which the current minute rate limit resets in RFC 7231 format.
X-RateLimit-Remaining-Minute	The number of requests remaining in the current minute rate limit window.
X-RateLimit-Reset-Day	The time at which the current day rate limit resets in RFC 7231 format.
X-RateLimit-Remaining-Day	The number of requests remaining in the current day rate limit window.

Response

OAuth credential object

Property	Type	Description
token_type `fixed`	`string`
expires_in `fixed`	`integer`	The token valid duration in seconds
access_token `fixed`	`string`	The access token to be used in OAuth `Bearer header`
refresh_token `fixed`	`string`	The refresh token to be used to get a new access token by `refresh token grant`

VCOM-API Migrations

v1 to v2

API versioning

The version of the API is appended to the base URL. No version in the URL defaults to the oldest available API version for backwards compatibility reasons.

Version	Base Url
v1	https://api.meteocontrol.de
v1	https://api.meteocontrol.de/v1
v2	https://api.meteocontrol.de/v2

Software End of Life for v1

VCOM API v1 will no longer be available after June 1, 2019

Authorization

VCOM API v2 officially supports OAuth 2.0, and basic authorization is also available but becomes deprecated.

Changed Endpoints

Systems measurements
- Allow multiple abbreviations now
Basics measurements
- The JSON response format is changed
- Allow multiple abbreviations now
Calculations measurements
- The JSON response format is changed
- Allow multiple abbreviations now
Get all tickets
- The JSON response no longer contains ‘assignee’, 'causeId’, 'includeInReports’, 'fieldService’ and 'outage’ information

System measurements

From now on the system measurements endpoint can deliver not just one measurement for all systems of your park but up to 5 measurements at once.

Basics measurements

From now on the basics measurements endpoint can deliver not just one measurement for all systems of your park but up to 5 measurements at once.

Consider given url:
https://api.meteocontrol.de/systems/ABCDE/basics/abbreviations/E_Z_EVU/measurements?from=2016-01-01T00:00:00+02:00&to=2016-01-01T00:15:00+02:00
The response format changed as follows:

Before

{
  "data": [
    {
      "timestamp": "2016-01-01T00:00:00+02:00",
      "value": 0
    },
    {
      "timestamp": "2016-01-01T00:15:00+02:00",
      "value": 0
    }
  ]
}

After

{
  "data": {
    "E_Z_EVU": [
      {
        "timestamp": "2016-01-01T00:00:00+02:00",
        "value": 0
      },
      {
        "timestamp": "2016-01-01T00:15:00+02:00",
        "value": 0
      }
    ]
  }
}

Calculations measurements

From now on the calculations measurements endpoint can deliver not just one measurement for all systems of your park but up to 5 measurements at once.

Consider given url:
https://api.meteocontrol.de/systems/ABCDE/calculations/abbreviations/E_N/measurements?from=2016-01-01T00:00:00+02:00&to=2016-01-01T00:15:00+02:00
The response format changed as follows:

Before

{
  "data": [
    {
      "timestamp": "2016-01-01T00:00:00+02:00",
      "value": 0
    },
    {
      "timestamp": "2016-01-01T00:15:00+02:00",
      "value": 0
    }
  ]
}

After

{
  "data": {
    "E_N": [
      {
        "timestamp": "2016-01-01T00:00:00+02:00",
        "value": 0
      },
      {
        "timestamp": "2016-01-01T00:15:00+02:00",
        "value": 0
      }
    ]
  }
}

New version 2 vcom-api-client released

To quickly get started you may use the new vcom-api-client tagged with version 2 from this repository

Removal of deprecated properties

With the new version 2 all deprecated properties were removed and aren’t supported anymore.

Endpoint name	Deprecated property	Property to use
Get all tickets	lastChange[from]	lastChangedAt[from]
Get all tickets	lastChange[to]	lastChangeAt[to]
Get all tickets	date[from]	createdAt[from]
Get all tickets	date[to]	createdAt[to]
Get all tickets	rectifiedOn[from]	rectifiedAt[from]
Get all tickets	rectifiedOn[to]	rectifiedAt[to]
Get single ticket	date	createdAt
Get single ticket	lastChange	lastChangedAt
Get single ticket	rectifiedOn	rectifiedAt
Get single ticket	causeId	cause
Update a ticket	rectifiedOn	rectifiedAt
Create a ticket	date	createdAt
Get single attachment	created	createdAt
Get all comments	date	createdAt
Get single comment	date	createdAt
Get all Histories for a ticket	timestamp	createdAt

Changelog

Date	Description
2025-09-01	Add alarm closure reason
2025-08-20	Increase get alarms count
2025-07-09	Add resolution parameter to calculate yield loss
2025-07-02	Add undetermined yield loss calculation option to API
2025-04-28	Add site-access for cmms endpoint
2025-04-24	Extend technical data endpoint to return systemConfigurations models
2025-03-20	Add a new resolution “interval” to the satellite data endpoint
2025-03-12	Add simulation for yield-losses endpoint
2024-12-11	Support considerPowerControl as query parameter in simulation endpoint
2024-11-18	Add uid/serial property in all data device models
2024-11-05	Disallow users from changing the real yield loss values with the flat-rate, peak, and simplified peak yield-losses endpoints
2024-10-23	Add inverter PR endpoint
2024-08-28	Add ticket yield-losses endpoint
2024-08-22	Add new property additionalInformation to SystemDetail model
2024-08-07	Add last data input endpoint
2024-08-01	Add manual and static yield loss calculation option to API
2024-07-31	Add single alarm endpoints to assign/unassign ticket and close alarm
2024-06-30	Remove the deprecated yield-losses endpoints that use the 2017 formulas
2024-06-20	Add ticket outage endpoints
2024-04-10	Implement the replace action for all yield-losses endpoints
2024-01-29	Remove v1
2024-01-10	Add category parameter to the forecast endpoint
2023-12-27	Support the yield loss calculation formulas defined by Bundesnetzagentur in 2020 and deprecate the 2017 formulas
2023-12-25	Add kpi targets endpoints
2023-10-31	Remove the yield-losses endpoints that didn’t specify the power control sources
2023-10-05	Triple minute rate
2023-10-04	Add endpoints with different power control sources for yield loss calculation
2023-09-07	Add satellite irradiance endpoint
2022-12-15	Add yield-losses endpoints
2022-08-22	Add environmental-savings endpoints
2022-04-20	Add ability to manipulate Ticket fieldService property
2022-04-01	Add alarms endpoints
2022-01-13	Add forecast endpoint
2022-01-13	Add cause property for ticket and ability to manipulate ticket cause
2021-03-02	Add status device endpoints
2021-02-09	Add simulation endpoints
2020-12-10	Add cmms endpoints
2020-06-22	Introduce filter for deviceIds to bulk endpoints
2020-04-01	Extend system endpoint to return simulation method
2020-03-30	Extending get tickets with fieldService response
2019-12-04	Add trackers endpoints
2019-11-27	Add virtual-meters endpoints
2019-08-06	New abbreviation CO2 under systems abbreviations, and add includeInterval option for bulk endpoints
2019-07-22	Add rate-limit for login endpoint
2019-06-26	Introduce filters for active only strings and/or abbreviations to bulk endpoints
2019-03-13	Remove the limitation of year resolution in measurement endpoints
2019-03-12	New abbreviation CO2 under calculations
2019-01-16	Forecasts endpoint introduced
2018-11-29	Basics, Calculations and systems abbreviation measurement support multiple abbreviations in request