NAV
cURL PHP
Version:

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 free of charge.

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:

Getting Started

Code snippet

    curl
    -u username:password
    -H "X-API-KEY: apiKey"
    'https://api.meteocontrol.de/<URL>'
<?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

Credentials (username, password)

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:

Authentication

Request (Basic)

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

Request (OAuth)

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

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 10 500
API 10.000 30 10.000
API 100.000 90 100.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'

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, e.g. 2010-01-01T00:00:00+00:00. 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.

Content Encoding

Request

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

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": "fake@mail.intra",
      "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;// 'fake@mail.intra'
    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) and PR (Performance Ratio).

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"
  ]
}
<?php
    /** @var string[] $abbreviations */
    echo $abbreviations[0]; // E_Z_EVU
    echo $abbreviations[1]; // G_M
    echo $abbreviations[2]; // PR

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(\DateTime::ATOM, '2016-11-01T00:00:00+02:00'))
        ->withDateTo(\DateTime::createFromFormat(\DateTime::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(\DateTime::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(\DateTime::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 required (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
  }
}
<?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

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": 1
      },
      {
        "vendor": "KACO new energy",
        "model": "Powador 3500xi",
        "count": 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;// 1
    echo $technicalData->inverters[1]->vendor;// KACO new energy
    echo $technicalData->inverters[1]->model;// Powador 3500xi
    echo $technicalData->inverters[1]->count;// 1

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 vendor string, model string, count integer
inverters fixed array vendor string, model string, count integer

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(\DateTime::ATOM, '2016-09-01T10:00:00+02:00'))
        ->withDateTo(\DateTime::createFromFormat(\DateTime::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

* 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)

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(\DateTime::ATOM, '2016-11-01T00:00:00+02:00'))
        ->withDateTo(\DateTime::createFromFormat(\DateTime::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(\DateTime::ATOM);// 2016-11-01T00:00:00+02:00
    echo $measurements[0]->value;// 0
    echo $measurements[1]->timestamp->format(\DateTime::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(\DateTime::ATOM, '2016-11-01T10:00:00+02:00'))
        ->withDateTo(\DateTime::createFromFormat(\DateTime::ATOM, '2016-11-01T10:05:00+02:00'));
    /** @var MeasurementsBulkReader $bulkData */
    $bulkData = $api->system('4DC11')->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 array $bulkDataArray */
    $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

* 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(\DateTime::ATOM, '2016-10-01T00:00:00+02:00'))
        ->withDateTo(\DateTime::createFromFormat(\DateTime::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(\DateTime::ATOM);// 2016-10-01T00:00:00+02:00
    echo $measurement[0]->value;// 0
    echo $measurement[1]->timestamp->format(\DateTime::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(\DateTime::ATOM, '2016-09-01T23:45:00+02:00'))
        ->withDateTo(\DateTime::createFromFormat(\DateTime::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 array $bulkDataArray */
    $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

* 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

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(\DateTime::ATOM, '2016-10-01T00:00:00+02:00'))
        ->withDateTo(\DateTime::createFromFormat(\DateTime::ATOM, '2016-12-31T23:59:59+01:00'));
    /** @var TimestampValue[] $yields */
    $yields = $this->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.

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(\DateTime::ATOM, '2016-10-21T11:00:00+02:00'))
        ->withDateTo(\DateTime::createFromFormat(\DateTime::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(\DateTime::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(\DateTime::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(\DateTime::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(\DateTime::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(\DateTime::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

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

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(\DateTime::ATOM, '2016-10-21T10:00:00+02:00'))
        ->withDateTo(\DateTime::createFromFormat(\DateTime::ATOM, '2016-10-21T10:05:00+02:00'));
     /** @var MeasurementsBulkReader $bulkReader */
    $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 array $bulkDataArray */
    $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

* 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)

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

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"
    },
    {
      "id": "12346",
      "name": "Meter 2"
    }
  ]
}
<?php
    /** @var Meter[] $meters */
    echo $meters[0]->id;// 12345
    echo $meters[0]->name;// Meter 1
    echo $meters[1]->id;// 12346
    echo $meters[1]->name;// Meter 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

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",
    "address": "1",
    "firmware": "1.0"
  }
}
<?php
    /** @var MeterDetail $meter */
    echo $meter->id;// 12345
    echo $meter->name;// Meter 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
address fixed string 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 $abbreviations */
    $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(\DateTime::ATOM, '2016-11-01T11:00:00+02:00'))
        ->withDateTo(\DateTime::createFromFormat(\DateTime::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(\DateTime::ATOM);// 2016-11-01T11:00:00+02:00
    echo $measurements["12345"]['E'][0]->value;// 7119.21
    echo $measurements["12345"]['E'][1]
        ->timestamp->format(\DateTime::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

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

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(\DateTime::ATOM, '2016-11-01T10:00:00+02:00'))
        ->withDateTo(\DateTime::createFromFormat(\DateTime::ATOM, '2016-11-01T10:05:00+02:00'));
     /** @var MeasurementsBulkReader $bulkReader */
    $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

* 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)

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)"
    },
    {
      "id": "10002",
      "name": "Irradiation sensor M&T / mc Si-420TC-T (4 - 20mA)"
    }
  ]
}
<?php
    /** @var Sensor[] $sensors */
    echo $sensors[0]->id;// 10001
    echo $sensors[0]->name;// Pyranometer SMPx (Modbus)
    echo $sensors[1]->id;// 10002
    echo $sensors[1]->name;// Irradiation sensor M&T / mc Si-420TC-T (4 - 20mA)

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

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)",
    "address": "7",
    "firmware": "1.0"
  }
}
<?php
    /** @var SensorDetail $sensor */
    echo $sensor->id;// 10001
    echo $sensor->name;// Pyranometer SMPx (Modbus)
    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
address fixed string 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(\DateTime::ATOM, '2016-10-21T20:00:00+02:00'))
        ->withDateTo(\DateTime::createFromFormat(\DateTime::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(\DateTime::ATOM);// 2016-10-21T20:00:00+02:00
    echo $measurements["10001"]['SRAD'][0]->value;// 177.2
    echo $measurements["10001"]['SRAD'][1]
        ->timestamp->format(\DateTime::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

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

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(\DateTime::ATOM, '2016-10-21T20:00:00+02:00'))
        ->withDateTo(\DateTime::createFromFormat(\DateTime::ATOM, '2016-10-21T20:05:00+02:00'));
     /** @var MeasurementsBulkReader $bulkReader */
    $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 array $bulkDataArray */
    $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

* 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)

Options for CSV format

The following query parameters are valid only if format is csv
For response example in CSV format, please check [HERE](https://github.com/meteocontrol/vcom-api-client/tree/master/tests/unit/lib/systems/responses/bulkCsv/getSensorBulk.csv.

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"
    },
    {
      "id": "20002",
      "name": "stringbox2"
    }
  ]
}
<?php
    /** @var Stringbox[] $stringboxes */
    echo $stringboxes[0]->id;// 20001
    echo $stringboxes[0]->name;// stringbox1
    echo $stringboxes[1]->id;// 20002
    echo $stringboxes[1]->name;// stringbox2

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

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": "abcd",
    "scaleFactor": 1.32
  }
}
<?php
    /** @var StringboxDetail $stringbox */
    echo $stringbox->id;// 20001
    echo $stringbox->name;// stringbox1
    echo $stringbox->address;// abcd
    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"
  }
}
<?php
    /** @var Abbreviation $abbreviation */
    echo $abbreviation->aggregation;// AVG
    echo $abbreviation->precision;// null
    echo $abbreviation->description;// Current DC
    echo $abbreviation->unit;// A

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
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(\DateTime::ATOM, '2016-10-21T11:00:00+02:00'))
        ->withDateTo(\DateTime::createFromFormat(\DateTime::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(\DateTime::ATOM);// 2016-10-21T11:00:00+02:00
    echo $measurements["20001"]['I1'][0]->value;// 177.2
    echo $measurements["20001"]['I1'][1]
        ->timestamp->format(\DateTime::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

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

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(\DateTime::ATOM, '2016-11-01T23:00:00+02:00'))
        ->withDateTo(\DateTime::createFromFormat(\DateTime::ATOM, '2016-11-01T23:05:00+02:00'));
     /** @var MeasurementsBulkReader $bulkReader */
    $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 array $bulkDataArray */
    $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

* 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)

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": ""
        },
        {
            "id": "145147",
            "name": ""
        }
    ]
}
<?php
    /** @var Battery[] $batteries */
    echo $batteries[0]->id;// 145146
    echo $batteries[0]->name;
    echo $batteries[1]->id;// 145147
    echo $batteries[1]->name;

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

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": "",
    "address": "bat1",
    "firmware": "1.0"
  }
}
<?php
    /** @var BatteryDetail $battery */
    echo $battery->id;// 145146
    echo $battery->name;
    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
address fixed string 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 $abbreviations */
    $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(\DateTime::ATOM, '2016-11-01T11:00:00+02:00'))
        ->withDateTo(\DateTime::createFromFormat(\DateTime::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(\DateTime::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(\DateTime::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

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

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(\DateTime::ATOM, '2016-10-10T11:00:00+02:00'))
        ->withDateTo(\DateTime::createFromFormat(\DateTime::ATOM, '2016-10-10T11:15:00+02:00'));
     /** @var MeasurementsBulkReader $bulkReader */
    $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 array $bulkDataArray */
    $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

* 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)

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"
        }
    ]
}
<?php
    /** @var PowerPlantController[] $powerPlantControllers */
    echo $powerPlantControllers[0]->id;// 163784
    echo $powerPlantControllers[0]->name;// 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

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",
    "address": "ppc-5bbc370ddb808",
    "firmware": null
  }
}
<?php
    /** @var PowerPlantControllerDetail $powerPlantController */
    echo $powerPlantController->id;// 163784
    echo $powerPlantController->name;// 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
address fixed string 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 $abbreviations */
    $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(\DateTime::ATOM, '2016-10-29T11:00:00+02:00'))
        ->withDateTo(\DateTime::createFromFormat(\DateTime::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(\DateTime::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(\DateTime::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

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

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(\DateTime::ATOM, '2016-10-29T18:00:00+02:00'))
        ->withDateTo(\DateTime::createFromFormat(\DateTime::ATOM, '2016-10-29T18:15:00+02:00'));
     /** @var MeasurementsBulkReader $bulkReader */
    $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_GRIDOP_ABS": 92.299999999999997,
      "PPC_P_SET_RPC_REL": 38.399999999999999,
      "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_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-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_GRIDOP_ABS": 91.5,
      "PPC_P_SET_RPC_REL": 56.700000000000003,
      "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_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 array $bulkDataArray */
    $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

* 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)

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

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": "fake@mail.intra",
      "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": "fake@mail.intra",
      "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": "fake@mail.intra",
      "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": "fake@mail.intra",
      "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": "fake@mail.intra",
      "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->user->id; // "123"
    echo $responsibilities->owner->user->title; // 'Mr.'
    echo $responsibilities->owner->user->firstName; // 'First Name'
    echo $responsibilities->owner->user->lastName; // 'Last Name'
    echo $responsibilities->owner->user->username; // 'user.name'
    echo $responsibilities->owner->user->email; // 'fake@mail.intra'
    echo $responsibilities->owner->user->language; // 'en'
    echo $responsibilities->owner->user->company; // 'Company'
    echo $responsibilities->owner->user->fax; // '0234567890'
    echo $responsibilities->owner->user->telephone; // '0234567891'
    echo $responsibilities->owner->user->cellphone; // '0987654321'
    echo $responsibilities->owner->user->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->user->id; // "123"
    echo $responsibilities->operator->user->title; // 'Mr.'
    echo $responsibilities->operator->user->firstName; // 'First Name'
    echo $responsibilities->operator->user->lastName; // 'Last Name'
    echo $responsibilities->operator->user->username; // 'user.name'
    echo $responsibilities->operator->user->email; // 'fake@mail.intra'
    echo $responsibilities->operator->user->language; // 'en'
    echo $responsibilities->operator->user->company; // 'Company'
    echo $responsibilities->operator->user->fax; // '0234567890'
    echo $responsibilities->operator->user->telephone; // '0234567891'
    echo $responsibilities->operator->user->cellphone; // '0987654321'
    echo $responsibilities->operator->user->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->user->id; // "123"
    echo $responsibilities->electrician->user->title; // 'Mr.'
    echo $responsibilities->electrician->user->firstName; // 'First Name'
    echo $responsibilities->electrician->user->lastName; // 'Last Name'
    echo $responsibilities->electrician->user->username; // 'user.name'
    echo $responsibilities->electrician->user->email; // 'fake@mail.intra'
    echo $responsibilities->electrician->user->language; // 'en'
    echo $responsibilities->electrician->user->company; // 'Company'
    echo $responsibilities->electrician->user->fax; // '0234567890'
    echo $responsibilities->electrician->user->telephone; // '0234567891'
    echo $responsibilities->electrician->user->cellphone; // '0987654321'
    echo $responsibilities->electrician->user->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->user->id; // "123"
    echo $responsibilities->invoiceRecipient->user->title; // 'Mr.'
    echo $responsibilities->invoiceRecipient->user->firstName; // 'First Name'
    echo $responsibilities->invoiceRecipient->user->lastName; // 'Last Name'
    echo $responsibilities->invoiceRecipient->user->username; // 'user.name'
    echo $responsibilities->invoiceRecipient->user->email; // 'fake@mail.intra'
    echo $responsibilities->invoiceRecipient->user->language; // 'en'
    echo $responsibilities->invoiceRecipient->user->company; // 'Company'
    echo $responsibilities->invoiceRecipient->user->fax; // '0234567890'
    echo $responsibilities->invoiceRecipient->user->telephone; // '0234567891'
    echo $responsibilities->invoiceRecipient->user->cellphone; // '0987654321'
    echo $responsibilities->invoiceRecipient->user->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->user->id; // "123"
    echo $responsibilities->alarmContact->user->title; // 'Mr.'
    echo $responsibilities->alarmContact->user->firstName; // 'First Name'
    echo $responsibilities->alarmContact->user->lastName; // 'Last Name'
    echo $responsibilities->alarmContact->user->username; // 'user.name'
    echo $responsibilities->alarmContact->user->email; // 'fake@mail.intra'
    echo $responsibilities->alarmContact->user->language; // 'en'
    echo $responsibilities->alarmContact->user->company; // 'Company'
    echo $responsibilities->alarmContact->user->fax; // '0234567890'
    echo $responsibilities->alarmContact->user->telephone; // '0234567891'
    echo $responsibilities->alarmContact->user->cellphone; // '0987654321'
    echo $responsibilities->alarmContact->user->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 = $this->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": "fake@mail.intra",
    "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;//"fake@mail.intra",
    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
    /** @var UserDetail $user */
    $criteria = new UserCriteria();
    $criteria->withUsername("user1.name");
    $user = $api->system('ABCDE')->users()->get($criteria);

Response

{
  "data": {
    "id": "123",
    "title": "Mrs.",
    "firstName": "First Name",
    "lastName": "Last Name",
    "username": "user1.name",
    "email": "fake@mail.intra",
    "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;//"fake@mail.intra",
    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(\DateTime::ATOM, '2016-01-01T00:00:00+02:00'))
        ->withLastChangedAtTo(\DateTime::createFromFormat(\DateTime::ATOM, '2016-01-31T00:00:00+02:00'))
        ->withCreatedAtFrom(\DateTime::createFromFormat(\DateTime::ATOM, '2016-04-01T00:00:00+02:00'))
        ->withCreatedAtTo(\DateTime::createFromFormat(\DateTime::ATOM, '2016-04-25T00:00:00+02:00'))
        ->withRectifiedAtFrom(\DateTime::createFromFormat(\DateTime::ATOM, '2016-04-25T00:00:00+02:00'))
        ->withRectifiedAtTo(\DateTime::createFromFormat(\DateTime::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",
      "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",
      "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]->status;// closed
    echo $tickets[0]->createdAt->format(\DateTime::ATOM);// 2016-01-01T12:00:00+02:00
    echo $tickets[0]->lastChangedAt->format(\DateTime::ATOM);// 2016-01-01T13:00:00+02:00
    echo $tickets[0]->rectifiedAt->format(\DateTime::ATOM);// 2016-01-01T13:00:00+02:00
    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]->status;// inProgress
    echo $tickets[1]->createdAt->format(\DateTime::ATOM);// 2016-02-01T12:00:00+02:00
    echo $tickets[1]->lastChangedAt->format(\DateTime::ATOM);// 2016-02-02T13:00:00+02:00
    echo $tickets[1]->rectifiedAt->format(\DateTime::ATOM);// 2016-02-02T13:00:00+02:00

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)
severity fixed (normal|high|critical|null)

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

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,
    "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 $tickets->description;// This is a description
    echo $ticket->summary;// This is a summary.
    echo $ticket->createdAt->format(\DateTime::ATOM);// 2016-01-01T12:00:00+02:00
    echo $ticket->lastChangedAt->format(\DateTime::ATOM);// 2016-01-01T13:00:00+02:00
    echo $ticket->rectifiedAt->format(\DateTime::ATOM);// 2016-01-01T14:00:00+02:00
    echo $ticket->assignee;// null
    echo $ticket->status;// inProgress
    echo $ticket->causeId;// 10
    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 string 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
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 float 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(\DateTime::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 string 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

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

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(\DateTime::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",
    "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

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

Response - Data

Property Type Description
ticketId fixed string Of the new ticket

Response - Paths

Method type Description
get fixed string GET 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 string 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": 661288,
      "createdAt": "2016-02-19T12:49:20+01:00",
      "comment": "Comment text",
      "username": "username",
      "firstName": "firstName",
      "lastName": "lastName"
    },
    {
      "commentId": 661286,
      "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;// 661288
    echo $comments[0]->createdAt->format(\DateTime::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;// 661286
    echo $comments[1]->createdAt->format(\DateTime::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/661288'
<?php
    /** @var CommentDetail comment */
    $comment = $api->ticket(123)->comment(661288)->get();

Response

{
  "data":{
    "commentId": 661288,
    "createdAt": "2016-02-19T12:49:20+01:00",
    "comment": "Comment text",
    "username": "username",
    "firstName": "firstName",
    "lastName": "lastName"
  }
}
<?php
    /** @var CommentDetail comment */
    echo $comment->commentId;// 661288
    echo $comment->createdAt->format(\DateTime::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": 454548
  }
}
<?php
    /** @var integer $commentId */
    echo $commentId;// 454548

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/454548'
<?php
    $comment = new CommentDetail();
    $comment->comment = 'New Comment';
    $api->ticket(123)->comment(454548)->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/454548'
<?php
    $api->ticket(123)->comment(454548)->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

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 string Ticket-ID

Response

Attachment array

Property Type Description
attachmentId fixed string 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",
    "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->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
creatorId fixed integer Creator Id

Create an attachment

Please note there’s a limit of 5 attachments per ticket.

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 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. Max decoded file size is 2MB
description required string File description

Response

Property Type Description
attachmentId fixed integers Attachment-ID
filename fixed string Name of the new attachment.

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(\DateTime::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(\DateTime::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(\DateTime::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(\DateTime::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

Login

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.

GET 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


Response

OAuth credentials 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

  1. Systems measurements
    • Allow multiple abbreviations now
  2. Basics measurements
    • The JSON response format is changed
    • Allow multiple abbreviations now
  3. Calculations measurements
    • The JSON response format is changed
    • Allow multiple abbreviations now
  4. 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
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 Version Description
2018-11-29 2.0.0 Basics, Calculations and systems abbreviation measurement support multiple abbreviations in request
2019-01-16 2.1.0 Forecasts endpoint introduced
2019-03-12 2.2.0 New abbreviation CO2 under calculations
2019-03-13 2.2.1 Remove the limitation of year resolution in measurement endpoints