Solar.

web Query API

Specification

Information Class: Public, Fronius International, Solar Energy, 27.01.2025

© Fronius International GmbH

Version 52.0 2025-01-27

Solar Energy

Fronius reserves all rights, in particular rights of reproduction, distribution and translation.
No part of this work may be reproduced in any way without the written consent of Fronius. It must not be saved,
edited, reproduced or distributed using any electrical or electronic system.
You are hereby reminded that the information published in this document, despite exercising the greatest of care
in its preparation, is subject to change and that neither the author nor Fronius can accept any legal liability.
Table of Contents

1 Version History .......................................................................................................................... 6

2 Introduction .............................................................................................................................. 7

2.1 About Fronius [Link] Query API ....................................................................................... 7

2.2 Usage of the Fronius [Link] Query API ............................................................................ 8

2.2.1 Target audience .................................................................................................................................... 8

2.2.2 How to start with Fronius [Link] Query API ............................................................................... 8

2.2.3 Data plans and pricing ........................................................................................................................ 9

3 General information............................................................................................................... 10

3.1 Key managament ................................................................................................................... 10

3.2 User impersonation ............................................................................................................... 12

3.3 Identification of PV systems ................................................................................................. 16

3.4 Pagination .............................................................................................................................. 17

3.5 Date and time formats .......................................................................................................... 17

3.5.1 Use time in the calling URL ............................................................................................................... 18

3.5.2 Time in response objects .................................................................................................................. 18

4 API Management Portal......................................................................................................... 19

4.1 Development section............................................................................................................. 19

4.1.1 Release information .......................................................................................................................... 19

4.1.2 System availability ............................................................................................................................. 20

4.1.3 Key management ............................................................................................................................... 21

4.2 Account section ...................................................................................................................... 22

4.2.1 Monthly reports ................................................................................................................................. 22

4.2.2 Billing information ............................................................................................................................. 23

5 Swagger UI.............................................................................................................................. 23

6 API Reference .......................................................................................................................... 26

6.1 User impersonation calls ...................................................................................................... 26

Table of Contents– 3
 6.1.1 Impersonate: Receive a JWT using userId and password ............................................................ 26

6.1.2 Impersonate: Refresh a JWT ............................................................................................................. 29

6.1.3 Impersonate: Revoke a JWT .............................................................................................................. 31

6.2 Generic information calls ...................................................................................................... 33

6.2.1 Info: Get release information ........................................................................................................... 33

6.2.2 Info: Get user information ................................................................................................................ 34

6.3 Metadata calls ........................................................................................................................ 37

6.3.1 Metadata: Get PV system information ............................................................................................ 37

6.3.2 Metadata: Count PV systems ........................................................................................................... 41

6.3.3 Metadata: Enumerate PV system IDs.............................................................................................. 43

6.3.4 Metadata: Get device information................................................................................................... 45

6.3.5 Metadata: Count devices .................................................................................................................. 59

6.3.6 Metadata: Enumerate device IDs .................................................................................................... 60

6.4 Aggregation calls ................................................................................................................... 62

6.4.1 Aggrdata: Aggregated energy data for a PV system .................................................................... 62

6.4.2 Aggrdata: Aggregated energy data for a device ........................................................................... 71

6.5 Historical data calls ................................................................................................................ 77

6.5.1 Histdata: Historical data for a PV system ....................................................................................... 77

6.5.1 Histdata: Historical data for a device .............................................................................................. 81

6.6 Realtime data calls ................................................................................................................. 92

6.6.1 Flowdata: Realtime power flow data of a PV system .................................................................... 92

6.6.2 Flowdata: Realtime power flow data of a device ........................................................................... 96

6.7 Weather data calls ............................................................................................................... 100

6.7.1 Limitations ........................................................................................................................................ 101

6.7.2 Weather: Current weather for a PV system ................................................................................. 101

6.7.3 Weather: Weather forecast for a PV system ................................................................................ 104

6.7.4 Weather: Energy forecast for a PV system ................................................................................... 107

6.8 System messages calls ........................................................................................................ 110

6.8.1 Messages: Get PV system messages ............................................................................................ 110

6.8.2 Messages: Count PV system messages ........................................................................................ 113

6.8.3 Messages: Get device system messages ...................................................................................... 114

6.8.4 Messages: Count device system messages ................................................................................. 116

Table of Contents– 4
7 Appendix ................................................................................................................................ 118

7.1 Response and error codes .................................................................................................. 118

7.1.1 HTML error codes ............................................................................................................................ 118

7.1.2 Detailed error codes ........................................................................................................................ 119

7.2 Response Headers ............................................................................................................... 123

7.2.1 Rate limit headers ............................................................................................................................ 123

7.2.2 Cache control headers (max-age).................................................................................................. 123

7.3 Channels ............................................................................................................................... 126

7.3.1 Channel list ....................................................................................................................................... 126

7.3.2 Channel types ................................................................................................................................... 139

7.4 Meteorological weather symbols ....................................................................................... 140

7.4.1 List of weather symbols .................................................................................................................. 140

7.5 Languages ............................................................................................................................ 143

7.6 Best practices and how-tos ................................................................................................. 144

7.6.1 Use filters for channels .................................................................................................................. 144

7.6.2 Determine power values from energy values from historical data ......................................... 144

7.6.3 Determine PV Energy and Load Energy ....................................................................................... 144

7.6.4 Determine if new systems were added to account .................................................................... 145

7.6.5 Grant permissions in [Link] ..................................................................................................... 145

Table of Contents– 5
 [Link] Query API manual

1 Version History
Version Modified Description
52.0 Jan 27, 2025 • Note to metadata filtering added
• Fixed endpoint description for weather calls
• Added filter information to GetUserInfo call
• Endpoint cleanup ([Link] vs. the older
[Link]/swqapi)
• Added information about API Management Portal
51.0 Oct 12, 2023 • Add new battery channels (powerflow)
• Updated battery metadata example
50.0 Aug 01, 2023 • Added channels for Submeters.
• Corrected "PowerPurchased" channel to "PowerPurchase".
• Updated EnergyExported and EnergyImported channels for
secondary meters
• Pilot example added
• Updated data plan details
49.0 Oct 12, 2022 • Updated sections Metadata calls, Aggregation calls, Historical data
calls, Realtime data calls, System messages calls:
• Added Wattpilot data.
• Updated some example responses.
• Minor corrections in section Weather data calls.
• Updated General information section.
• Updated Supporting UIs section.
• Updated channel list:
• Added Wattpilot data
• Removed reference to outdated Aggregation calls

Version History– 6
 [Link] Query API manual

Version Modified Description

48.0 Dec 09, 2021 • Added notes to GenerateJwt call.
• Added status code information for maintenance windows.
• Updated device metadata:
• Provided lists for Smart Meter locations and categories.
• Provided list for sensor types.
• Updated device metadata:
• Added missing datalogger IDs.
• Improved examples, e.g. a GEN24 PV system.
• Added revoke JWT call.
• Updated metadata calls with meteo filter.
• Clarifications in error tables.
• Removed "PowerBattDischarge" channel from channel list, and
updated description of "PowerBattCharge".
• Clarified positive/negative values for power flow data.
• Clarified 3301 error code for historical data.
• Added datalogger and Ohmpilot examples to device metadata.
• Removed Fronius SSO login method.
47.0 Apr 21, 2021 • Updated camelCase notation in examples for system messages.
46.0 Apr 02, 2021 • Changed supported channel information for aggregated and
historical data requests.
• Updated [Link] screenshots, error code lists and channel list.
45.0 Feb 02, 2021 • Version history added.
• Added additional information about [Link] Premium to
chapter "User impersonation".
• Updated chapter "Determine power values from energy values" in
Appendix.

2 Introduction

2.1 About Fronius [Link] Query API

Fronius [Link]

The Fronius [Link] online portal allows users to easily and conveniently monitor, analyze and
compare their photovoltaic systems by visualizing energy flows and displaying PV (photovoltaic)
yields. Intelligent analysis functions ensure that yield losses are reliably avoided.

Fronius [Link] Query API

Introduction– 7
 [Link] Query API manual

The [Link] Query Application Programming Interface (SWQAPI) is an application-to-application

interface for accessing the raw data of PV systems stored on [Link] servers. Two applications
(client requesting data and [Link] delivering data) are interacting via API to each other without
any user intervention, so that the client application can e.g. display information to end users or do
detailed analysis of the data.

2.2 Usage of the Fronius [Link] Query API

2.2.1 Target audience

SWQAPI is intended to be used by customers who want to have their own visualization of their PV
systems or integrate the data into their existing applications.

For example, a utility which, next to its core business (electricity supply), offers PV systems to its
customers, most likely already provides an online portal or an app where customers can check their
electricity consumption. The utility might want to extend the functionality of the portal and also
show the data of the customers’ PV systems. The utility has just to fetch the PV data from the
[Link] servers via the API and then visualize it for its customers in its portal.

Another example would be an O&M (operation and monitoring) company which offers extensive
monitoring solutions to their customers. Often an O&M company supports PV systems from
different vendors and does not want to use multiple monitoring portals. By fetching the PV data
from [Link] via API the O&M company can easily integrate the data in its monitoring solution.

2.2.2 How to start with Fronius [Link] Query API

Trial access

A Fronius Sales Representative can enable the trial access for interested customers which contains
the same PV systems that are available in the [Link] demo portal. Using the trial keys,
interested customers can use the Swagger UI to test the SWQAPI. In that case an interested
customer does not need to have his/her own [Link] account or any PV system linked to a
[Link] account.

Introduction– 8
 [Link] Query API manual

Unlimited access

In order to access and use the SWQAPI customers need to have an active [Link] account
([Link] and complete and sign an order form. More details and contact
information can be found at [Link]

After completing the registration, please make yourself familiar with the key management. You
need to create at least one key in the [Link] user settings, which you can then use
programmatically. We recommend getting started by using the Swagger UI (https://
[Link]/swqapi/[Link]) and test a few calls first, e.g. by enumerating PV systems and
showing their metadata (unique ID, name of system, address, etc). Once you are more familiar with
the SWQAPI, have a look at the energy flows which show the current status of PV systems. Fronius
also recommends comparing the API results with information and diagrams you see in the
[Link] UI.

Note: If you don't see any PV systems in your account at all, you likely need to add PV systems to
your account either by registering a new PV system in [Link] for this account or by adding
guest or supervisor permission for this account to an already existing PV system. Guest
permissions are sufficient to see most of the data. However, if you want to see service messages
for a certain PV system you need supervisor permission to view them.

From there, continue with exploration. If you want to show power curves for the last few days, have
a look at the historical data which gives you 5 min granularity to draw production and consumption
diagrams. If you want to go further into the past, use the aggregation method which has daily,
monthly or annual energy data available for you.

Beta environment

For preview of new functionalities, Fronius provides a Beta environment (available at the
URL [Link] It works like the Production environment, i.e. uses the
same API keys to access the same PV systems, so you can test your applications against it.

2.2.3 Data plans and pricing

Trial access is free but there are costs for unlimited access. The costs depend on the number of
queried data points per month. Below is a list showing how the end points and data points are
billed.

Response to the following calls are not billed:

• Release information
• PV system information
• Count of systems

Introduction– 9
 [Link] Query API manual

• List of system IDs

• Count of devices
• List of device IDs

Each response to the following calls counts as just one data point:
• PV system information
• Detailed information about systems
• Detailed information about devices
• Power flow data
• Current weather data

The responses for the following calls count as multiple data points:
• Aggregation data: per data point/channel and timestamp; CO2 savings (4 channels) count as
one (per timestamp); Profits (3 channels) count as one (per timestamp)
• Historical data: per data point/channel and timestamp (e.g. one hour of EnergyExported with
5 minute log interval counts as 12 data points)
• Service messages: each service message counts as data point
• Energy forecast: each 15min/1hr EnergyExported forecast counts as one data point
• Weather forecast: one data point per day

Information about pricing and data plans, more details and example calculations can be found at
[Link] Please contact your local sales representative for
further details about pricing.

3 General Information

3.1 Key management

API users must include valid API keys in the header of their requests. These keys are generated by
authorized users within the Fronius API Management Portal. Each authorized user can have
multiple API keys, which are restricted according to their permissions in [Link].

API keys have the following attributes:

General Information– 10
 [Link] Query API manual

A unique ID for the API key, e.g.

Access key ID "FKIAFEF58CFEFA94486F9C804CF6077A01AB". Access keys are 36
characters long and start with the "FKIA" prefix.
A secret value (GUID), e.g. "47c076bc-23e5-4949-37a6-4bcfcf8d21d6",
which you need to know for authorization of API calls.
Access key value Please note: When you create a key, please save it to a secure key store.
Fronius does not have means to recover a lost key. If you lose a key, you
need to recreate a new one.
A key can be active or passive, and you can toggle its status. Active keys
Active status
can be used, passive keys cannot be unless you toggle them.
You can set a validity period for a key, e.g. if you want to enforce key
renewals.
By default, new keys do not have an expiry date; they can be used as long
Expiry date
as you do not delete them, or set an expiry date and the expiry date is not
yet reached. Once you define an expiry date, you cannot delete the expiry
date any longer nor extend the expiry date into the future.
This attribute indicates the time and date when the key was last used for
Last used date an API call. This way you can identify unused keys and delete or
deactivate them for security reasons.

API calls require the access key ID and access key value to be included in the HTTP header.

Examples:

HTTP header example

GET [Link] HTTP/1.1

AccessKeyId: FKIAFEF58CFEFA94486F9C804CF6077A01AB
AccessKeyValue: 47c076bc-23e5-4949-37a6-4bcfcf8d21d6

CURL example

curl -X GET "[Link] -H "accept: application/json"

-H "AccessKeyId: FKIAFEF58CFEFA94486F9C804CF6077A01AB" -H "AccessKeyValue:
47c076bc-23e5-4949-37a6-4bcfcf8d21d6"

General Information– 11
 [Link] Query API manual

3.2 User impersonation

There are situations for applications which require the applications to see PV systems in context of
another user, e.g. a service provider might want to show and analyze the data of their customers.
For such use cases SWQAPI supports impersonation using JWT tokens in addition to API keys.

[Link] Premium

Please note that access to [Link] Premium features through the API is only possible if
the impersonated user owns a [Link] Premium membership.

JWT token attributes

A long string, identifying the customer and providing access to him, for example:
eyJ4NXQiOiJOR1psTURSbFkyRXlaR1kzTkRjNU1UVm1PR0UwWWpGaVpXWTBaam
cxWV
dOa09EWmtNRE5rTVEiLCJraWQiOiJOR1psTURSbFkyRXlaR1kzTkRjNU1UVm1PR0
Uw
[Link]
9oY
XNoIjoiS2hLZVZsc0lPXy1tWDhvZkJZSzdJZyIsImF1ZCI6IlljNHhtcEIyVnlyR2p
hcUlraGoxbXJEOFZ6VWEiLCJzdWIiOiJodWV0dG5lci50aG9tYXNybmRAZnJvbml1
c
JWT token y5jb20iLCJuYmYiOjE1ODUyOTQ2NjcsImF6cCI6IlljNHhtcEIyVnlyR2phcUlraGo
value xbXJEOFZ6VWEiLCJhbXIiOlsicGFzc3dvcmQiXSwiaXNzIjoiJHtjYXJib24ucHJvd
G9jb2x9OlwvXC8ke2NhcmJvbi5ob3N0fVwvb2F1dGgyXC9vaWRjZGlzY292ZXJ5Iiw
iZXhwIjoxNTg1Mjk4MjY3LCJpYXQiOjE1ODUyOTQ2Njd9.HUXi1sySzyLqx2e0dLpr
0sszi-
YiI3nGNB4GZDDwIwVHUHC4s6ED8BqfvkfFn3s45LkvJQEvqb_Wd3QtMGnzOL
EZ3RdK3A8GWdsDChVq_nzlP4FGC6b5lPoz9Xi6mH_pcxt36rzA2-vjl_e6cTOrTXsI
eIzOjZVNSZRAJ4-A5HpmEuvraoArAGUqc_yTntbfALhfJQkfsjoDAJRAfZXLknTvDK
m2vMd0-
uXjTQHM2dKAWGAz6r39cLQ24sFIIC7MDgIp4GpNVBCLFSNzkK7mV3fSEQvg
IdAFMhEP4CY4lMTItLxdfRKxcf5SA7o2fU0-_710frdFYvrkesorDCiyfg

An expiry time (UTC time) for the JWT; a Fronius JWT is valid for exactly one hour
JWT expiry and needs to be refreshed periodically.
date Note: A JWT stays valid even if the customer changes his password (for a maximum
of one hour).
Refresh A token which can be used to refresh a JWT.
token

General Information– 12
 [Link] Query API manual

Creating a JWT and using it in a SWQAPI call

You can pass another user's Fronius [Link] user ID and password, and you receive a JWT and a
refresh token. Please be careful about the user's password and protect it against leaking.

When you call SWQAPI, you need to pass the JWT in addition to your API key credentials. It is not
possible to call without the API key credentials.

Example with Postman how to create a JWT:

In the following example we see the token values returned in the body. You need the refreshToken
and the jwtToken. Copy the jwtToken value.

In the Authorization section select "Bearer" and then paste the jwtToken value from previous call.

General Information– 13
 [Link] Query API manual

General Information– 14
 [Link] Query API manual

Examples how to use a JWT:

HTTP header example

GET [Link] HTTP/1.1

AccessKeyId: FKIAFEF58CFEFA94486F9C804CF6077A01AB
AccessKeyValue: 47c076bc-23e5-4949-37a6-4bcfcf8d21d6
Authorization: Bearer
eyJ4NXQiOiJPVEZsT1RCbE9HSmhZak15TlRFNU5XVTJPVGd6TnpVd04yTmpOVFV5WlRFeU1tRTNZVEZoTmciL
CJraWQiOiJPVEZsT1RCbE9HSmhZak15TlRFNU5XVTJPVGd6TnpVd04yTmpOVFV5WlRFeU1tRTNZVEZoTmciLC
JhbGciOiJSUzI1NiJ9.eyJhdF9oYXNoIjoicXZUYi04RzJvQnR5Qko1SEt5Z1l3USIsInN1YiI6ImtyZW5odW
Jlci5hbGV4YW5kZXJAZnJvbml1cy5jb20iLCJzdHJlZXRfYWRkcmVzcyI6IkZyb25pdXNwbGF0eiAxIiwiZ2V
uZGVyIjoiMSIsImFtciI6WyJDdXN0b21BdXRoZW50aWNhdG9yTG9jYWxNYWluIl0sImlzcyI6Imh0dHBzOlwv
XC9sb2dpbi5mcm9uaXVzLmNvbVwvb2F1dGgyXC90b2tlbiIsImNvbnRhY3RfaWQiOiJmYzY0NWVjNi00NmQ1L
WU5MTEtOTEyOS0wMDUwNTZhMjYxNDAiLCJzb2xhcndlYl9wcmVtaXVtX2V4cGlyYXRpb25fZGF0ZSI6IjIwMj
AtMDUtMTJUMjI6MDA6MDBaIiwic2lkIjoiOWE4NWYzMTgtMWE2Yi00NDMyLTliZGQtZGZkOGUzNWMwNjk2Iiw
iYXpwIjoibWZfbzlpVEF5S2VtTkxRVGE2U3A2SFlvbkNJYSIsImV4cCI6MTU3MjI1NzY4NywiaWF0IjoxNTcy
MjU0MDg3LCJlbWFpbCI6ImtyZW5odWJlci5hbGV4YW5kZXJAZnJvbml1cy5jb20iLCJwcmVmZXJyZWRfbGFuZ
3VhZ2UiOiJkZSIsImxvY2FsaXR5IjoiZGUiLCJzb2xhcndlYl91c2VyaWQiOiI4RkM3NzVFRC03QjlBLTREMz
YtQTcwNi1BQTkzMDA5RjNGRjkiLCJncm91cHMiOiJJbnRlcm5hbFwvZXZlcnlvbmUiLCJnaXZlbl9uYW1lIjo
iQWxleGFuZGVyIiwic29sYXJ3ZWJfcHJlbWl1bV9yb2xlIjoiMSIsIm5vbmNlIjoiYXNkZiIsImRhdGFfY29u
dGFjdF9jb21wbGV0ZSI6InllcyIsImF1ZCI6Im1mX285aVRBeUtlbU5MUVRhNlNwNkhZb25DSWEiLCJjX2hhc
2giOiJFWDZZS3NwaUxHY2tDc3RFNW02VmtnIiwibmJmIjoxNTcyMjU0MDg3LCJjb3VudHJ5X2lzb19jb2RlIj
oiQVQiLCJsb2NhdGlvbiI6IldlbHMiLCJwb3N0YWxfY29kZSI6IjQ2MDAiLCJmYW1pbHlfbmFtZSI6IktyZW5
odWJlciIsImRhdGFfYWNjb3VudF92YWxpZCI6InllcyJ9.Qzywri3WV6RHjv9Ng9fDCkzxPRprrNBx63bvoGk
bxa0hhyJVIdT132ylCyvmp84t_agvRG7Gk8HFcn5XrWcJ126mM-
CMQ5VFSLIyCmZm_vwoPXuOsk_pC1clX890WcqKDy3uaA3UdlLGYOke8kg-
ueQIxfkme1gSb2q0LEATaS8wdYYW-ODakMFd7zQvlRLJnXVXICeHwXrZu68fDRjdUlulu_13Ggi-
yHrtZTji_My_J57iMgJHTLaf7Gw3QzMMaZ85Kyz3jvqQgLFPylZgNBoz6ztzEdYd5Fhu-
kccibD662q9D7R5PHN88zY9ieVl9RYPyJZ5Rjk6qIYxb5Km6w

CURL example

curl -X GET "[Link] -H "accept: application/json"

-H "AccessKeyId: FKIAFEF58CFEFA94486F9C804CF6077A01AB" -H "AccessKeyValue:
47c076bc-23e5-4949-37a6-4bcfcf8d21d6" -H "Authorization: Bearer
eyJ4NXQiOiJPVEZsT1RCbE9HSmhZak15TlRFNU5XVTJPVGd6TnpVd04yTmpOVFV5WlRFeU1tRTNZVEZoTmciL
CJraWQiOiJPVEZsT1RCbE9HSmhZak15TlRFNU5XVTJPVGd6TnpVd04yTmpOVFV5WlRFeU1tRTNZVEZoTmciLC
JhbGciOiJSUzI1NiJ9.eyJhdF9oYXNoIjoicXZUYi04RzJvQnR5Qko1SEt5Z1l3USIsInN1YiI6ImtyZW5odW
Jlci5hbGV4YW5kZXJAZnJvbml1cy5jb20iLCJzdHJlZXRfYWRkcmVzcyI6IkZyb25pdXNwbGF0eiAxIiwiZ2V
uZGVyIjoiMSIsImFtciI6WyJDdXN0b21BdXRoZW50aWNhdG9yTG9jYWxNYWluIl0sImlzcyI6Imh0dHBzOlwv
XC9sb2dpbi5mcm9uaXVzLmNvbVwvb2F1dGgyXC90b2tlbiIsImNvbnRhY3RfaWQiOiJmYzY0NWVjNi00NmQ1L
WU5MTEtOTEyOS0wMDUwNTZhMjYxNDAiLCJzb2xhcndlYl9wcmVtaXVtX2V4cGlyYXRpb25fZGF0ZSI6IjIwMj
AtMDUtMTJUMjI6MDA6MDBaIiwic2lkIjoiOWE4NWYzMTgtMWE2Yi00NDMyLTliZGQtZGZkOGUzNWMwNjk2Iiw
iYXpwIjoibWZfbzlpVEF5S2VtTkxRVGE2U3A2SFlvbkNJYSIsImV4cCI6MTU3MjI1NzY4NywiaWF0IjoxNTcy
MjU0MDg3LCJlbWFpbCI6ImtyZW5odWJlci5hbGV4YW5kZXJAZnJvbml1cy5jb20iLCJwcmVmZXJyZWRfbGFuZ
3VhZ2UiOiJkZSIsImxvY2FsaXR5IjoiZGUiLCJzb2xhcndlYl91c2VyaWQiOiI4RkM3NzVFRC03QjlBLTREMz
YtQTcwNi1BQTkzMDA5RjNGRjkiLCJncm91cHMiOiJJbnRlcm5hbFwvZXZlcnlvbmUiLCJnaXZlbl9uYW1lIjo

General Information– 15
 [Link] Query API manual

iQWxleGFuZGVyIiwic29sYXJ3ZWJfcHJlbWl1bV9yb2xlIjoiMSIsIm5vbmNlIjoiYXNkZiIsImRhdGFfY29u
dGFjdF9jb21wbGV0ZSI6InllcyIsImF1ZCI6Im1mX285aVRBeUtlbU5MUVRhNlNwNkhZb25DSWEiLCJjX2hhc
2giOiJFWDZZS3NwaUxHY2tDc3RFNW02VmtnIiwibmJmIjoxNTcyMjU0MDg3LCJjb3VudHJ5X2lzb19jb2RlIj
oiQVQiLCJsb2NhdGlvbiI6IldlbHMiLCJwb3N0YWxfY29kZSI6IjQ2MDAiLCJmYW1pbHlfbmFtZSI6IktyZW5
odWJlciIsImRhdGFfYWNjb3VudF92YWxpZCI6InllcyJ9.Qzywri3WV6RHjv9Ng9fDCkzxPRprrNBx63bvoGk
bxa0hhyJVIdT132ylCyvmp84t_agvRG7Gk8HFcn5XrWcJ126mM-
CMQ5VFSLIyCmZm_vwoPXuOsk_pC1clX890WcqKDy3uaA3UdlLGYOke8kg-
ueQIxfkme1gSb2q0LEATaS8wdYYW-ODakMFd7zQvlRLJnXVXICeHwXrZu68fDRjdUlulu_13Ggi-
yHrtZTji_My_J57iMgJHTLaf7Gw3QzMMaZ85Kyz3jvqQgLFPylZgNBoz6ztzEdYd5Fhu-
kccibD662q9D7R5PHN88zY9ieVl9RYPyJZ5Rjk6qIYxb5Km6w"

3.3 Identification of PV systems

Each PV system has its own unique ID (PV system ID) which is a mandatory parameter for many
API endpoints. A PV system ID can be determined by using the /pvsystems API endpoints that
provide information about all PV systems linked to the user’s account. The PV system ID can also
be found in the URL of the system in Fronius [Link] (highlighted in screenshot below).

Please note that a PV system can only be accessed through the API if the user has access to it (by
ownership or access permission).

General Information– 16
 [Link] Query API manual

3.4 Pagination
When returning many results, Fronius APIs make use of HATEOAS principles to support
pagination. Additionally, the APIs return a "totalItemsCount" object.

The default pagination limit is 50, the maximum pagination limit is 1000 currently.

Example:

Example JSON return object with pagination information (see the "links" object type)

{
"pvSystemIds": [
...
],
"links": {
"first": "[Link]
"prev": null,
"self": "[Link]
"next": "[Link]
"last": "[Link]
"totalItemsCount": 173
}
}

Please note that, for better readability, we do not show the pagination objects in the
command reference documentation.

3.5 Date and time formats

SWQAPI supports extended UTC time formats (ISO 8601).

The principle format is either "yyyyMMddThhmmssTZD" or "yyyy-MM-ddThh:mm:ssTZD" - where

TZD is a timezone designator (either "Z" or an offset).

http encoding speciality

If you are using a positive timezone offset, please use "%2b" instead of "+". Negative
timezone offsets are not affected by the http encoding.
Examples:
• 2018-10-11T13:00:00%2b01:00 instead of 2018-10-11T13:00:00+01:00
• 2018-10-11T13:00:00-01:00

General Information– 17
 [Link] Query API manual

3.5.1 Use time in the calling URL

Example URIs, all showing the same time request

// get all historical temperature values (Temp1 channel) using different timezones in
the URL
// all examples below are for October 10th, 2018, from 11am to 12am zulu time

GET [Link]/pvsystems/20bb600e-019b-4e03-9df3-a0a900cda689/histdata?
from=2018-10-10T11:00:00Z&to=2018-10-11T12:00:00Z?channel=Temp1
// zulu time notation

GET [Link]/pvsystems/20bb600e-019b-4e03-9df3-a0a900cda689/histdata?
from=20181010T120000%2b01:00&to=20181011T130000&2b01:00?channel=Temp1
// CET (+01:00 offset to zulu time), compact encoding
// please note that the "+" in the offset needs to be encoded with "%2b"

GET [Link]/pvsystems/20bb600e-019b-4e03-9df3-a0a900cda689/histdata?
from=2018-10-10T06:00:00-05:00&to=2018-10-11T07:00:00-05:00?channel=Temp1
// EST (-05:00 offset to zulu time)

Additionally, you can also use local time of the PV system.

Example URIs, all showing the same time request

// get all historical temperature values (Temp1 channel) for October 10th, 2018, from
11am to 12am local time of the PV system

GET [Link]/pvsystems/20bb600e-019b-4e03-9df3-a0a900cda689/histdata?
from=2018-10-10T11:00:00&to=2018-10-11T12:00:00?channel=Temp1
// local time, depending on where PV system 20bb600e-019b-4e03-9df3-a0a900cda689 is
located

3.5.2 Time in response objects

When returning data, SWQAPI will either return zulu or local UTC time, extended encoding.

By default SWQAPI delivers zulu time, but you can use the "timezone" parameter to request
conversion to the local time zone where the PV system is located. Local time (i.e. without timezone
offset) is not returned, but when you ignore the offset, you have the system's local time.

General Information– 18
 [Link] Query API manual

Example responses, all showing the same time

// data for August 31st, 2019; 12am zulu time

// timezone=zulu
"logDateTime": "2019-07-31T12:00:00Z"
// zulu time notation

// timezone=local variations, depending on the timezone location of the queried PV

system
"logDateTime": "2019-07-31T12:00:00+00:00"
// assuming PV system is in zulu time (without offset time)

"logDateTime": "2019-07-31T13:00:00+01:00"
// assuming PV system is in CET (+01:00 offset to zulu time)

"logDateTime": "2019-07-31T07:00:00-05:00"
// assuming PV system is in EST (-05:00 offset to zulu time)

4 API Management Portal

The Fronius API Management is available at [Link]

4.1 Development section

4.1.1 Release information

An overview about the latest release API version is provided on the Release information tab.

API Management Portal– 19

 [Link] Query API manual

4.1.2 System availability

The operational history for the last few few months can be checked on the System availability tab.
Here you can see the average system availability for the last 30 days, last 6 months or last 12
months.

On the right hand side, there are two more sections.

• A link to [Link] is provided.

API Management Portal– 20

 [Link] Query API manual

[Link] is an external service which also works when [Link] is down. If an incident
happens and [Link] is down, Fronius will post status updates here, because [Link]
services may not be able to show appropriate messages.

Additionally, [Link] keeps incident history information.

• Announcements for Planned maintenance will be published here as well.

4.1.3 Key management

For managing API keys, go to Key management. Here you can view and manage your keys. Please
note that the time information (creation date, expiry date, and last used date) is given in UTC zulu
time.

Actions:
• If you want to create a new key, please press the + New key button. This will create a new key.
You can either copy and paste the API key ID and its secret value, or download a JSON file
containing the API key ID and its secret value.
• You can give a name and description to each key. To do so, please press the three dots in
the menu column and then select Edit.
Please note: Expired keys cannot be renamed.
• If you want to set an expiry date please press the three dots in the menu column and then
select Edit.
Please note: Expiry dates cannot be removed or changed to a later date once they are set. If
a key is expired, you can no longer edit it.
• To deactivate a key, press the three dots in the menu and then select Deactivate. To activate
an inactive key, use Activate in the same menu.

API Management Portal– 21

 [Link] Query API manual

• Only expired or inactive keys can be deleted. To do so, please press the three dots in the
menu column and then select Delete.

Recommendations:
• If you have multiple developers, create separate keys for each developer. Create another key
for automated testing, staging and production systems.
• If a key is compromised, especially keys for production, please renew the key:
• Create a new key.
• Set an expiry date for the old key, or deactivate the old key as soon as the new one is
deployed.
• If you want to implement periodic key renewals for security reasons:
• Create a new key.
• Set an expiry date for the old key which gives you enough overlapping time to push the
new key to all relevant systems.

4.2 Account section

4.2.1 Monthly reports

You can get information about monthly consumption on this page.

API Management Portal– 22

 [Link] Query API manual

4.2.2 Billing information

For double-checking contractual information, go to Billing information. Here you can view your
contract start and end time. Some licenses can be initially unlimited, indicated by the infinite
symbol in the End date column (as in the example below).

Actions:
• If your Finance/Purchase department needs a Purchase order number on the invoice, you
can enter one. To do so, press the Edit button on the right and enter the purchase order
number in the following dialog.

5 Swagger UI
If you'd like to explore the API and experiment with it without writing any code, you can do so in the
Swagger UI.

When working with the Swagger UI, you need to enter the API keys only once.

Press the Authorize

button in Swagger UI.

Swagger UI– 23
 [Link] Query API manual

Enter both the accesskey

ID and its value. Press the
Authorize button in both
sections.

Swagger UI– 24
 [Link] Query API manual

Finally, close the dialog

using the x button on the
top right corner.

Result: The Authorize

button shows a closed
lock now.
Swagger UI does not verify the keys

The closed lock in the Authorize button does not mean that
your access keys are correct. They are verified directly by
the APIs you call.

Swagger UI– 25
 [Link] Query API manual

Impersonation / Bearer
key:

If you want to use the

impersonation feature
you need to get an JWT
for the user you want to
impersonate (by using
the /jwt endpoint first,
see section Impersonate:
Receive a JWT using the
Fronius login).

Press the Authorize

button in Swagger UI
again. Under Bearer enter
the JWT and press
Authorize. Close the
dialog using the x button
on the top right corner.

Please note that authentication is reset if a page refresh is done.

The Swagger UI for the SWQAPI can be found here: [Link]

6 API Reference

6.1 User impersonation calls

6.1.1 Impersonate: Receive a JWT using userId and password

Use cases for web developers
• I want to login to Fronius using a customer's user ID and password. (E.g. the customer enters
the Fronius login credentials on my website and I am able to store it.)

Security notes

API Reference– 26
 [Link] Query API manual

Storing customer passwords needs to be carefully designed, because passwords can

easily leak. Please make use of operating system capabilities, such as iCloud
Keychain, Android Keystore, Credential Manager in Windows, etc.
Additionally, please consider GDPR and other PII regulation.

• I used the former "ThirdParty API" (predecessor of SWQAPI) and used the customer's
credentials to login. When I migrate from ThirdParty API to SWQAPI I can reuse the
credentials, thus the customer does not notice a change.

Developer best practice

Please use JWT tokens carefully:

• A JWT token is valid for one hour.
• After this hour is passed you will get a 401 http error code. Please use the refresh
mechanism to get an updated JWT token instead of creating a new one.
• Only if the refresh call gives you an error again, you should generate a new JWT
token using this call.
• Note: Refresh tokens are valid for 40 days.

Make use of the scope parameter!

• Use a unique scope for you application.
• If you implement an application for mobile devices, a good idea is to use UUIDs to
prevent that one login on device A logs out users on device B.

Methods

End point and

Method Event name Description
objects
POST /iam/jwt GenerateJwt Generates a JWT and refresh token
pair by passing credentials.

Filters and parameters

Filter Description
?scope=<scope> Optional but recommended: Scope of the token for multiple
sessions. The scope can be generic or specific for a user agent
(e.g. a device or app ID).
Scopes allow users to be logged in from multiple devices and in
[Link] in parallel.

Example calls

API Reference– 27
 [Link] Query API manual

POST [Link]/iam/jwt?scope=my-app.23423af9afe0af0
// generates a new JWT for impersonation in a specific scope

Input objects

JSON object input construction:

Type Objects
credentials • userId (String)
• password (String)

Example input

{
"userId": "mike@[Link]",
"password": "thisIsMyVeryPrivatePassword!"
}

Response objects

JSON object answer construction:

Type Objects
token information • refreshToken (String)
• jwtToken (String)
• jwtTokenExpiration (UTC time)

Example responses

{
"refreshToken": "98a47454-b650-34b8-9a8c-27adae447ab7",
"jwtToken":
"eyJ4NXQiOiJOR1psTURSbFkyRXlaR1kzTkRjNU1UVm1PR0UwWWpGaVpXWTBaamcxWVdOa09EWmtNRE5rTVEi
LCJraWQiOiJOR1psTURSbFkyRXlaR1kzTkRjNU1UVm1PR0UwWWpGaVpXWTBaamcxWVdOa09EWmtNRE5rTVEiL
CJhbGciOiJSUzI1NiJ9.eyJhdF9oYXNoIjoiS2hLZVZsc0lPXy1tWDhvZkJZSzdJZyIsImF1ZCI6IlljNHhtc
EIyVnlyR2phcUlraGoxbXJEOFZ6VWEiLCJzdWIiOiJodWV0dG5lci50aG9tYXNybmRAZnJvbml1cy5jb20iLC
JuYmYiOjE1ODUyOTQ2NjcsImF6cCI6IlljNHhtcEIyVnlyR2phcUlraGoxbXJEOFZ6VWEiLCJhbXIiOlsicGF
zc3dvcmQiXSwiaXNzIjoiJHtjYXJib24ucHJvdG9jb2x9OlwvXC8ke2NhcmJvbi5ob3N0fVwvb2F1dGgyXC9v
aWRjZGlzY292ZXJ5IiwiZXhwIjoxNTg1Mjk4MjY3LCJpYXQiOjE1ODUyOTQ2Njd9.HUXi1sySzyLqx2e0dLpr
0sszi-
YiI3nGNB4GZDDwIwVHUHC4s6ED8BqfvkfFn3s45LkvJQEvqb_Wd3QtMGnzOLEZ3RdK3A8GWdsDChVq_nzlP4F
GC6b5lPoz9Xi6mH_pcxt36rzA2-vjl_e6cTOrTXsIeIzOjZVNSZRAJ4-
A5HpmEuvraoArAGUqc_yTntbfALhfJQkfsjoDAJRAfZXLknTvDKm2vMd0-

API Reference– 28
 [Link] Query API manual

uXjTQHM2dKAWGAz6r39cLQ24sFIIC7MDgIp4GpNVBCLFSNzkK7mV3fSEQvgIdAFMhEP4CY4lMTItLxdfRKxcf
5SA7o2fU0-_710frdFYvrkesorDCiyfg",
"jwtTokenExpiration": "2020-03-27T08:37:48.8710788Z"
}

6.1.2 Impersonate: Refresh a JWT

Use cases for web developers
• I want to refresh an expired JWT token.

Developer best practice

Please use refresh tokens instead of logging in again and again

• A refresh token is valid for 40 days and allows you to create new JWT tokens without
having the user to provide the login credentials.
• Creating new login tokens are costly. Therefore each refresh saves computing power
and storage memory on the Fronius side, thus also login performance.

Notes:
• After a refresh, you get a new refresh token. The old refresh token gets invalidated.

Methods

End point and

Method Event name Description
objects
PATCH /iam/jwt/{refresh- RefreshJwt Refreshes a JWT and refresh token
token} pair.

Please note that the old

refresh token gets invalidated
by this call.

Filters and parameters

API Reference– 29
 [Link] Query API manual

Filter Description
?scope=<scope> Optional but recommended: Scope of the token for multiple
sessions, which needs to be the same scope when the original
token was created. The scope can be generic or specific for a
user agent (e.g. a device or app ID).
Scopes allow users to be logged in from multiple devices and in
[Link] in parallel.

Must not include any scope values not originally granted,

and if omitted is treated as equal to the originally
granted scope.

Example calls

PATCH [Link]/iam/jwt/98a47454-b650-34b8-9a8c-27adae447ab71?scope=my-
app.23423af9afe0af0
// refreshes an existing token and generates a new one, uses the original scope

Response objects

JSON object answer construction:

Type Objects
refreshToken • String
jwtToken • String
jwtTokenExpiration • String (UTC time)

Example responses

{
"refreshToken": "c5f51670-e2ca-35b7-acc2-c32c8ceebc69",
"jwtToken":
"eyJ4NXQiOiJPVEZsT1RCbE9HSmhZak15TlRFNU5XVTJPVGd6TnpVd04yTmpOVFV5WlRFeU1tRTNZVEZoTmci
LCJraWQiOiJPVEZsT1RCbE9HSmhZak15TlRFNU5XVTJPVGd6TnpVd04yTmpOVFV5WlRFeU1tRTNZVEZoTmciL
CJhbGciOiJSUzI1NiJ9.eyJhdF9oYXNoIjoicXZUYi04RzJvQnR5Qko1SEt5Z1l3USIsInN1YiI6ImtyZW5od
WJlci5hbGV4YW5kZXJAZnJvbml1cy5jb20iLCJzdHJlZXRfYWRkcmVzcyI6IkZyb25pdXNwbGF0eiAxIiwiZ2
VuZGVyIjoiMSIsImFtciI6WyJDdXN0b21BdXRoZW50aWNhdG9yTG9jYWxNYWluIl0sImlzcyI6Imh0dHBzOlw
vXC9sb2dpbi5mcm9uaXVzLmNvbVwvb2F1dGgyXC90b2tlbiIsImNvbnRhY3RfaWQiOiJmYzY0NWVjNi00NmQ1
LWU5MTEtOTEyOS0wMDUwNTZhMjYxNDAiLCJzb2xhcndlYl9wcmVtaXVtX2V4cGlyYXRpb25fZGF0ZSI6IjIwM
jAtMDUtMTJUMjI6MDA6MDBaIiwic2lkIjoiOWE4NWYzMTgtMWE2Yi00NDMyLTliZGQtZGZkOGUzNWMwNjk2Ii
wiYXpwIjoibWZfbzlpVEF5S2VtTkxRVGE2U3A2SFlvbkNJYSIsImV4cCI6MTU3MjI1NzY4NywiaWF0IjoxNTc
yMjU0MDg3LCJlbWFpbCI6ImtyZW5odWJlci5hbGV4YW5kZXJAZnJvbml1cy5jb20iLCJwcmVmZXJyZWRfbGFu

API Reference– 30
 [Link] Query API manual

Z3VhZ2UiOiJkZSIsImxvY2FsaXR5IjoiZGUiLCJzb2xhcndlYl91c2VyaWQiOiI4RkM3NzVFRC03QjlBLTREM
zYtQTcwNi1BQTkzMDA5RjNGRjkiLCJncm91cHMiOiJJbnRlcm5hbFwvZXZlcnlvbmUiLCJnaXZlbl9uYW1lIj
oiQWxleGFuZGVyIiwic29sYXJ3ZWJfcHJlbWl1bV9yb2xlIjoiMSIsIm5vbmNlIjoiYXNkZiIsImRhdGFfY29
udGFjdF9jb21wbGV0ZSI6InllcyIsImF1ZCI6Im1mX285aVRBeUtlbU5MUVRhNlNwNkhZb25DSWEiLCJjX2hh
c2giOiJFWDZZS3NwaUxHY2tDc3RFNW02VmtnIiwibmJmIjoxNTcyMjU0MDg3LCJjb3VudHJ5X2lzb19jb2RlI
joiQVQiLCJsb2NhdGlvbiI6IldlbHMiLCJwb3N0YWxfY29kZSI6IjQ2MDAiLCJmYW1pbHlfbmFtZSI6IktyZW
5odWJlciIsImRhdGFfYWNjb3VudF92YWxpZCI6InllcyJ9.Qzywri3WV6RHjv9Ng9fDCkzxPRprrNBx63bvoG
kbxa0hhyJVIdT132ylCyvmp84t_agvRG7Gk8HFcn5XrWcJ126mM-
CMQ5VFSLIyCmZm_vwoPXuOsk_pC1clX890WcqKDy3uaA3UdlLGYOke8kg-
ueQIxfkme1gSb2q0LEATaS8wdYYW-ODakMFd7zQvlRLJnXVXICeHwXrZu68fDRjdUlulu_13Ggi-
yHrtZTji_My_J57iMgJHTLaf7Gw3QzMMaZ85Kyz3jvqQgLFPylZgNBoz6ztzEdYd5Fhu-
kccibD662q9D7R5PHN88zY9ieVl9RYPyJZ5Rjk6qIYxb5Km6w",
"jwtTokenExpiration": "2019-12-18T13:24:19Z"
}

6.1.3 Impersonate: Revoke a JWT

Use cases for web developers
• I want to revoke a refresh token, e.g. when the user logs out from my app
Note: Technically it is not possible to revoke the JWT token, too, but it expires automatically within
one hour. If you want to "revoke" a JWT token, please discard it instead.

Methods

Method End point and objects Event name Description

DELETE /iam/jwt/{refresh-token} RevokeJwt Revokes a JWT refresh token

Filters and parameters

n/a

Example calls

DELETE [Link]/iam/jwt/98a47454-b650-34b8-9a8c-27adae447ab7
// revokes an existing refresh token

Response objects

n/a

Example responses

API Reference– 31
 [Link] Query API manual

n/a

API Reference– 32
 [Link] Query API manual

6.2 Generic information calls

6.2.1 Info: Get release information

Use cases for web developers
• I want to know the version number of the REST API which I am using.

Methods

End point and

Method Event name Description
objects
GET /info/release GetInfoRelease Retrieves version and release date
information about the REST API.

Filters and parameters

n/a

Example calls

GET [Link]/info/release
// retrieves the API's full version number and release date

Response objects

JSON object answer construction:

Type Objects
info/release • ReleaseVersion (String)
• ReleaseDate (String, Date)

Example responses

{
"releaseVersion": "[Link]",
"releaseDate": "2019-10-07T"
}

API Reference– 33
 [Link] Query API manual

6.2.2 Info: Get user information

Use cases for web developers
• I want to show the customer's address data.
• I want to know if the customer is a premium customer.
• I want to know if the customer has accepted the (latest) Terms of Use.

Methods

End point and

Method Event name Description
objects
GET /info/user GetInfoUser Returns information about either the
SWQAPI user or the impersonated
user.

Filters and parameters

Filter Description
?details=<"name", "address", Specifies which details of the JSON response
"contractInformation", "settings", object shall be returned by the GetUserInfo call.
"accountAttributes", "favoritePvSystems">

Example calls

GET [Link]/info/user
// returns user information

GET [Link]/info/user?details=name,address
// returns user's name and address information

Response objects

JSON object answer construction:

API Reference– 34
 [Link] Query API manual

Type Objects
user • name (Object)
• title (String) - e.g. "Mr.", "Mrs."
• firstName (String)
• lastName (String)
• address (Object)
• street (String)
• zipCode (String)
• city (String)
• state (String)
• country (String)
• contactInformation (Object)
• telephone (String)
• email (String)
• settings (Object)
• timeZone (String) - in Olson format
• dateFormat (String) -
"[Link]", "[Link]", "[Link]",
"DD/MM/YYYY", "MM/DD/YYYY", or "YYYY/MM/DD"
• timeFormat (String) - "12h", "24h"
• language (String) - in ISO language code
• accountAttributes (Object)
• premiumMembership (Boolean)
• termsAcceptedLatest (Boolean)
• termsAcceptedVersion (Integer)
• premiumMembershipEnddate (String; DateTime)
• favoritePvSystems (Array of GUIDs, optional)

Example responses

{
"name": {
"title": "Mr.",
"firstName": "John",
"lastName": "Doe"
},
"address": {
"street": "Froniusplatz 1",
"zipCode": "4600",
"city": "Wels",
"state": "Upper Austria",
"country": "Austria"
},
"contractInformation": {

API Reference– 35
 [Link] Query API manual

"telephone": "+123456789",
"email": "[Link]@[Link]"
},
"settings": {
"timeZone": "Europe/Berlin",
"dateFormat": "[Link]",
"timeFormat": "24h",
"language": "en"
},
"accountAttributes": {
"premiumMembership": true,
"termsAcceptedLatest": true,
"premiumMembershipEnddate": "2024-12-31T23:59:59Z",
"termsAcceptedVersion": 2
}
}

In the JSON object part "contactInformation" is unfortunately a typo: For not breaking the
API, we keep "contractInformation" (with the "r"). Please excuse any inconvenience.

API Reference– 36
 [Link] Query API manual

6.3 Metadata calls

This set contains methods to retrieve
• the number of PV systems linked to the user’s account,
• a list of all PV system IDs,
• detailed information about the PV systems,
• the number of devices of a given PV system,
• a list of all devices of a given PV system and
• detailed information about the devices of a PV system

6.3.1 Metadata: Get PV system information

This call returns detailed meta information for one or more PV systems that are linked to the user’s
account (e.g. through ownership or guest/supervisor permission).

Use cases for web developers

• I want to get the meta information of all or specific PV systems: such as name, location, peak
power, picture, activation date etc.

Methods

End point and

Method Event name Description
objects
GET /pvsystems GetSystemMetaDataList Returns a list of all PV systems for the
user. The list is a JSON array
containing PV systems and their
metadata.
Parameters allow pagination ("offset"
& "limit"), or filtering for specific PV
system attributes ("type"; for example,
if "type"="ohmpilot" you only get PV
systems which have an Ohmpilot).
GET /pvsystems/{pv- GetSystemMetaData Returns metadata of the PV system
system-id} with the given ID, including metadata
for the system's devices.
Filters do not apply.

Filters and parameters

Filter Description
?offset=<offset>&limit=<limit> Supports pagination, returns pv-systems from a starting
<offset> and returning not more than <limit> items.

API Reference– 37
 [Link] Query API manual

Filter Description
?type=<devicetype> Type filter - one or more (comma separated, no spaces)
types of devices that a PV system should contain:
• inverter
• sensor
• battery
• smartmeter
• ohmpilot
• datalogger
• evcharger
?meteo=<level> Filters for systems with extended (meteo=pro) weather
data or with just basic (meteo=light) weather data.

Multiple filters will be processed with OR logic, e.g. ?type=sensor,battery will return PV
systems that contain at least a sensor OR a battery.

Example calls

GET [Link]/pvsystems
// retrieves metadata of all PV systems

GET [Link]/pvsystems?offset=200&limit=50
// returns metadata of 50 PV systems, starting at offset 200

GET [Link]/pvsystems?type=battery
// returns metadata of all PV systems which have a battery (caution: does not
retrieve the battery device info)

GET [Link]/pvsystems/20bb600e-019b-4e03-9df3-a0a900cda689
// returns metadata of a specific PV system

GET [Link]/pvsystems?meteo=pro
// returns metadata of all PV systems which have a "pro" weather information
available (which is normally only one PV system in the account)

Response objects

JSON object answer construction:

API Reference– 38
 [Link] Query API manual

Type Objects
PV systems • lastImport (String, UTC timestamp)
• installationDate (String, UTC timestamp)
• pvSystemId (String)
• name (String)
• address (Object)
• street (String)
• zipCode (String)
• city (String)
• state (String)
• country (String, ISO 3166-1 alpha-2 format)
• timezone (String, Olson format)
• pictureURL (String, URL)
• peakPower (Number)
• meteoData (String)

Example responses

Example for a single PV system

{
"pvSystemId": "04d81b82-7861-4e36-8e7f-41036ce711a4",
"name": "Fronius AT Wels Reception Hybrid",
"address": {
"country": "AT",
"zipCode": "4600",
"street": "Günter Fronius Straße 1",
"city": "Thalheim bei Wels",
"state": "OÖ"
},
"pictureURL": "[Link]
pvSystemId=04d81b82-7861-4e36-8e7f-41036ce711a4&pictureId=20991838-16d7-4a9a-83fd-
a75b00b34211",
"peakPower": 5000.0,
"installationDate": "2000-01-01T00:00:00Z",
"lastImport": "2020-03-27T06:03:42Z",
"meteoData": "light",
"timeZone": "Europe/Berlin"
}

Example for multiple PV systems

API Reference– 39
 [Link] Query API manual

"pvSystems": [
{
"pvSystemId": "20bb600e-019b-4e03-9df3-a0a900cda689",
"name": "Fronius AUS Melbourne",
"address": {
"country": "AU",
"zipCode": "3043",
"street": " _",
"city": "Tullamarine",
"state": null
},
"pictureURL": "[Link]
pvSystemId=20bb600e-019b-4e03-9df3-
a0a900cda689&pictureId=dbe22d74-02cd-480d-8565-410b3dffccce",
"peakPower": 12880.0,
"installationDate": "2011-06-01T00:00:00Z",
"lastImport": "2020-02-14T02:36:08Z",
"meteoData": "light",
"timeZone": "Australia/Sydney"
},
{
"pvSystemId": "83535831-3e55-46b4-a48c-a4e500ddcd1b",
"name": "Fronius AT Sattledt Hybrid",
"address": {
"country": "AT",
"zipCode": "4",
"street": "Froniusstrasse 1",
"city": "Sattledt",
"state": "OÖ"
},
"pictureURL": "[Link]
pvSystemId=83535831-3e55-46b4-a48c-a4e500ddcd1b&pictureId=bb4af026-540a-fb66-
e053-0204ff0a5ac0",
"peakPower": 5001.0,
"installationDate": "2000-01-01T00:00:00Z",
"lastImport": "2018-01-16T00:25:04Z",
"meteoData": "light",
"timeZone": "Europe/Berlin"
},
{
"pvSystemId": "04d81b82-7861-4e36-8e7f-41036ce711a4",
"name": "Fronius AT Wels Reception Hybrid",
"address": {
"country": "AT",
"zipCode": "4600",
"street": "Günter Fronius Straße 1",
"city": "Thalheim bei Wels",
"state": "OÖ"
},
"pictureURL": "[Link]
pvSystemId=04d81b82-7861-4e36-8e7f-41036ce711a4&pictureId=20991838-16d7-4a9a-83fd-
a75b00b34211",
"peakPower": 5000.0,

API Reference– 40
 [Link] Query API manual

"installationDate": "2000-01-01T00:00:00Z",
"lastImport": "2020-03-27T06:03:42Z",
"meteoData": "light",
"timeZone": "Europe/Berlin"
},
{
"pvSystemId": "0794d488-1d9e-467c-91c1-d89342949c60",
"name": "Fronius AT SAT Testraum 1PN",
"address": {
"country": "AT",
"zipCode": "4650",
"street": "Bahnhofstraße 4/4 ",
"city": "Lambach",
"state": "OÖ"
},
"pictureURL": "[Link]
pvSystemId=0794d488-1d9e-467c-91c1-d89342949c60&pictureId=e594903f-49a5-
ed47-9f5a-4d685da7a233",
"peakPower": 175000.0,
"installationDate": "2000-01-01T00:00:00Z",
"lastImport": "2020-01-13T07:36:36Z",
"meteoData": "light",
"timeZone": "Europe/Berlin"
},
{
"pvSystemId": "85896da3-bb2a-47f7-9c6e-2909dd44832c",
"name": "Sippi 1",
"address": {
"country": "AU",
"zipCode": "2600",
"street": "Perth Ave",
"city": "Canberra",
"state": "ACT"
},
"pictureURL": "[Link]
bb2a-47f7-9c6e-2909dd44832c&pictureId=a6bfb87e-2263-4c68-bc46-a7a00065859c",
"peakPower": 41901.0,
"installationDate": "2000-01-01T00:00:00Z",
"lastImport": "2020-03-27T06:30:53Z",
"meteoData": "light",
"timeZone": "Europe/Berlin"
}
]
}

6.3.2 Metadata: Count PV systems

This call returns the number of all PV systems that are linked to the user’s account (e.g. through
ownership or guest/supervisor permission).

API Reference– 41
 [Link] Query API manual

Use cases for web developers

• I want to know how many PV systems I can access. (Needed for subsequent enumeration and
detail calls.)
• I want to know how many PV systems I need to show in the UI, so I can prepare memory and
pagination.

Methods

End point and

Method Event name Description
objects
GET /pvsystems-count GetSystemCount Returns the count of all PV systems.
Filters can be applied to return only
the number of PV systems with
certain devices (e.g. inverters,
Ohmpilots, batteries etc).

Filters and parameters

Filter Description
?type=<devicetype> Type filter - one or more (comma separated, no spaces)
types of devices whose messages should be shown:
• inverter
• sensor
• battery
• smartmeter
• ohmpilot
• datalogger
• evcharger
?meteo=<level> Filters for systems with extended (meteo=pro) weather data
or with just basic (meteo=light) weather data.

Multiple filters will be processed with OR logic, e.g. ?type=sensor,battery will return PV
systems that contain at least a sensor OR a battery.

Example calls

GET [Link]/pvsystems-count
// counts all PV systems

GET [Link]/pvsystems-count?type=battery,smartmeter
// counts all PV systems with batteries or smartmeters

API Reference– 42
 [Link] Query API manual

Response objects

JSON object answer construction:

Type Objects
n/a • count (Number)

Example responses

{
"count": 4
}

6.3.3 Metadata: Enumerate PV system IDs

This call returns a list of the PV system IDs of all PV systems that are linked to the user’s account
(e.g. through ownership or guest/supervisor permission). The IDs are required for other calls to
query data from those systems.

Use cases for web developers

• I want to enumerate all PV systems which I can access. With the IDs I can scan these systems
in subsequent calls.
• I want to know how many devices I need to show in the UI, so I can prepare memory and
pagination.

Methods

End point and

Method Event name Description
objects
GET /pvsystems-list GetSystemIdList Returns the IDs of PV systems.
Parameters allow pagination ("offset"
& "limit"), or filtering for specific PV
system attributes ("type"; for example,
if "type"="battery" you only get PV
systems which have a battery).

Filters and parameters

API Reference– 43
 [Link] Query API manual

Filter Description
?offset=<offset>&limit=<limit> Supports pagination, returns pv-systems from a starting
<offset> and returning not more than <limit> items. The
limit parameter is limited to 1000. If limit is not set, 50 is
being used.
?type=<devicetype> Type filter - one or more (comma separated, no spaces)
types of devices whose messages should be shown:
• inverter
• sensor
• battery
• smartmeter
• ohmpilot
• datalogger
• evcharger
?meteo=<level> Filters for systems with extended (meteo=pro) weather
data or with just basic (meteo=light) weather data.

Multiple filters will be processed with OR logic, e.g. ?type=sensor,battery will return PV
systems that contain at least a sensor OR a battery.

Example calls

GET [Link]/pvsystems-list
// returns all PV system IDs

GET [Link]/pvsystems-list?offset=200&limit=50
// returns PV system IDs, starting at offset 200 and returning a page of 50 items

GET [Link]/pvsystems-list?type=battery
// returns PV system IDs which have a battery

GET [Link]/pvsystems-list?meteo=light
// returns PV system IDs which have "light" weather information available

Response objects

JSON object answer construction:

Type Objects
n/a • pvSystemIds (Array of Strings)

API Reference– 44
 [Link] Query API manual

Example responses

{
"pvSystemIds": [
"7eb46213-e165-44a2-82aa-88969f11847f",
"2b16033e-b842-4bf5-ae10-a3e4a14d297b",
"f51f544a-65f5-40e7-add5-0256fc3ca660",
"9e52c557-5fd5-41e0-ac6d-ad62f4556a27",
"3e0f7c5e-fa06-4346-937f-b21d6c903a9b",
"e187f87b-98ff-475e-b6fd-bfa3445cd848",
"0ae70a7d-6448-4fc7-9425-8610ddccd0f0",
"28603795-20ac-4456-a6cc-4bc6002deb56",
"fdc077a9-ca23-4edc-866a-99d38f4d8042",
"db2252b2-8ade-438c-8da5-889cccfa4036",
"e5bf41b6-d2df-446e-83d6-a41c0100041b",
"bcb9c5b6-cae8-40d2-9a4e-865f1365e29d",
"fa5f45cd-9b86-4709-bda8-4e0183c4f379",
"cc648cd7-70df-4e64-a215-ac2d2e556508",
"ef6fe5dc-4bb9-4d18-97eb-a1b600b6cc3e",
"046173e7-2d74-4e9b-ade3-a5e7014db4dc",
"26d01aef-fe32-4676-a9b9-4f59263c2ba5"
],
"links": {
"first": "[Link]
"prev": null,
"self": "[Link]
"next": null,
"last": "[Link]
"totalItemsCount": 17
}
}

totalItemsCount does not count items within this response, it counts overall available number of
systems.

6.3.4 Metadata: Get device information

Use cases for web developers
• I want to get the meta information of all or specific devices a specific PV systems has: such
as device types, capabilities, device detail information, attached sensors etc.

Methods

API Reference– 45
 [Link] Query API manual

End point and

Method Event name Description
objects
GET /pvsystems/{pv- GetDeviceMetaDataList Returns a list of PV components for a
system-id}/ given PV system. The list is a JSON
devices array containing devices and their
metadata.
Filters allow pagination and filtering of
device types.
GET /pvsystems/{pv- GetDeviceMetaData Returns the metadata information of
system-id}/ the requested PV device of a PV
devices/{device-id system with the given ID.
} (Serial number, model (inverter type,
Ohmpilot, battery, Smart Meter),
manufacturer, ...)

Filters and parameters

Filter Description
?offset=<offset>&limit=<limit> Supports pagination, returns devices from a starting
<offset> and returning not more than <limit> items.
?type=<devicetype> Type filter - one or more (comma separated, no spaces)
types of devices that a PV system should contain:
• inverter
• sensor
• battery
• smartmeter
• ohmpilot
• datalogger
• evcharger
?isActive=<state> Filters for active (isActive=true) or inactive
(isActive=false) devices only.

Example calls

GET [Link]/pvsystems/20bb600e-019b-4e03-9df3-a0a900cda689/devices
// returns metadata of all devices in the given PV system

GET [Link]/pvsystems/20bb600e-019b-4e03-9df3-a0a900cda689/devices?
type=inverter
// returns metadata for all inverters in the given PV system

API Reference– 46
 [Link] Query API manual

GET [Link]/pvsystems/20bb600e-019b-4e03-9df3-a0a900cda689/devices?
offset=0&limit=5
// returns the metadata of the first five devices in the given PV system

GET [Link]/pvsystems/20bb600e-019b-4e03-9df3-a0a900cda689/devices/
d2e61bf2-8dd7-4ba1-8733-d55d738c4679
// returns the metadata of a specific device

Response objects

JSON object answer construction:

API Reference– 47
 [Link] Query API manual

Type Objects Type Objects

Inverter • deviceType (String - Battery • deviceType (String -
"Inverter") "Battery")
• deviceId (String) • deviceID (String)
• deviceName (String) • deviceName (String)
• deviceManufacturer (String • deviceManufacturer
- usually "Fronius") (String)
• serialnumber (String) • serialNumber (String)
• deviceTypeDetails (String) • dataloggerId (String)
• dataloggerId (String) • maxChargePower
• nodeType (Integer) (Number)
• numberMPPTrackers • maxDischargePower
(Number) (Number)
• numberPhases (Number - 1 • maxSOC (Number)
to 3) • minSOC (Number)
• peakPower (Dictionary) • capacity (Number)
• dc1 (Number) • firmware (Object)
• dc2 (Number) • updateAvailable
• ... (Boolean)
• installedVersion
New inverter types can (String)
have more than two • availableVersion
strings. If there are (String)
more than two strings, • isActive (Boolean)
they will be added to • activationDate (String,
the peakPower object UTC timestamp)
as "dcN" (where N is • deactivationDate
the number of the (String, UTC
string). timestamp)

• nominalAcPower (Number)
• firmware (Object)
• updateAvailable
(Boolean)
• installedVersion
(String)
• availableVersion
(String)
• isActive (Boolean)
• activationDate (String, UTC
timestamp)
• deactivationDate (String,
UTC timestamp)

API Reference– 48
 [Link] Query API manual

Type Objects Type Objects

Sensor • deviceType (String - Ohmpilot • deviceType (String -
"Sensor") "Ohmpilot")
• deviceID (String) • deviceID (String)
• deviceName (String) • deviceName (String)
• deviceManufacturer • deviceManufacturer
(String) (String - "Fronius")
• firmware (Object) • serialnumber (String)
• updateAvailable • dataloggerId (String)
(Boolean) • firmware (Object)
• installedVersion • updateAvailable
(String) (Boolean)
• availableVersion • installedVersion
(String) (String)
• isActive (Boolean) • availableVersion
• activationDate (String, UTC (String)
timestamp) • isActive (Boolean)
• deactivationDate (String, • activationDate (String,
UTC timestamp) UTC timestamp)
• dataloggerId (String) • deactivationDate
• sensors (Array of objects) (String, UTC
• sensorType (String) timestamp)
• sensorName (String) • sensors (Array of
• isActive (Boolean) objects)
• activationDate • sensorType
(String, UTC (String)
timestamp) • sensorName
• deactivationDate (String -
(String, UTC "Temperature")
timestamp) • isActive (Boolean)
• activationDate
(String, UTC
timestamp)
• deactivationDate
(String, UTC
timestamp)

API Reference– 49
 [Link] Query API manual

Type Objects Type Objects

Smart Meter • deviceType (String - EVCharger • deviceType (String -
"SmartMeter") "EVCharger")
• deviceID (String) • deviceID (String)
• deviceName (String) • deviceName (String -
• deviceManufacturer "WattPilot")
(String) • deviceManufacturer
• deviceCategory (String) (String - "Fronius")
• deviceLocation (String) • serialnumber (String)
• serialNumber (String) • dataloggerId (String)
• dataloggerId (String) • firmware (Object)
• firmware (Object) • updateAvailable
• updateAvailable (Boolean)
(Boolean) • installedVersion
• installedVersion (String)
(String) • availableVersion
• availableVersion (String)
(String) • isActive (Boolean)
• isActive (Boolean) • activationDate (String,
• activationDate (String, UTC UTC timestamp)
timestamp) • deactivationDate
• deactivationDate (String, (String, UTC
UTC timestamp) timestamp)
• isOnline (Boolean)

API Reference– 50
 [Link] Query API manual

Type Objects
Datalogger • deviceType (String -
"Datalogger")
• deviceID (String)
• deviceName (String)
• deviceManufacturer
(String - "Fronius")
• firmware (Object)
• updateAvailable
(Boolean)
• installedVersion
(String)
• availableVersion
(String)
• isActive (Boolean)
• activationDate (String,
UTC timestamp)
• deactivationDate
(String, UTC
timestamp)
• dataloggerId (String)
• isOnline (Boolean)

Example responses

Example for an inverter

{
"deviceType": "Inverter",
"deviceId": "aff28818-5cd0-4075-8def-a3e3014b43c2",
"deviceName": "Symo Hybrid 5.0-3-S",
"deviceManufacturer": "Fronius",
"serialNumber": null,
"deviceTypeDetails": "Fronius Symo Hybrid 5.0-3-S",
"dataloggerId": "239.14294",
"nodeType": 97,
"numberMPPTrackers": 1,
"numberPhases": 3,
"peakPower": {
"dc1": 6510.0
},
"nominalAcPower": 5000.0,
"firmware": {
"updateAvailable": false,
"installedVersion": null,

API Reference– 51
 [Link] Query API manual

"availableVersion": "fro27372"
},
"isActive": true,
"activationDate": "2014-11-14T00:00:00Z",
"deactivationDate": null
}

Example for another inverter

{
"deviceType": "Inverter",
"deviceId": "8b6a8f4b-57cb-48c3-899f-71ca78f14627",
"deviceName": "Primo 5.0-1",
"deviceManufacturer": "Fronius",
"serialNumber": "27185462",
"deviceTypeDetails": "Fronius Primo 5.0-1",
"dataloggerId": "240.196164",
"nodeType": 97,
"numberMPPTrackers": 2,
"numberPhases": 1,
"peakPower": {
"dc1": 5000.0,
"dc2": null
},
"nominalAcPower": 5000.0,
"firmware": {
"updateAvailable": false,
"installedVersion": null,
"availableVersion": "fro27372"
},
"isActive": true,
"activationDate": "2021-09-22T00:00:00Z",
"deactivationDate": null
}

Example for a sensor

{
"deviceType": "Sensor",
"deviceId": "484d8603-64db-44d3-9b54-3de5895054c1",
"deviceName": "Sensor Card / Box (2)",
"deviceManufacturer": "Fronius",
"firmware": {
"updateAvailable": false,
"installedVersion": "",
"availableVersion": ""
},
"isActive": true,

API Reference– 52
 [Link] Query API manual

"activationDate": null,
"deactivationDate": null,
"dataloggerId": "240.347585",
"sensors": [
{
"sensorName": "Insolation",
"sensorType": "Insolation",
"isActive": true,
"activationDate": "2014-05-29T00:00:00Z",
"deactivationDate": null
},
{
"sensorName": "Temperature1",
"sensorType": "Temperature",
"isActive": true,
"activationDate": "2014-05-29T00:00:00Z",
"deactivationDate": null
}
]
}

Example for a datalogger (SnapInverter DataManagerr)

{
"deviceType": "Datalogger",
"deviceId": "2e303432-3931-3136-3634-000000000000",
"deviceName": "Datalogger",
"deviceManufacturer": "Fronius",
"firmware": {
"updateAvailable": true,
"installedVersion": "3.16.7-1",
"availableVersion": "3.18.7-1"
},
"isActive": true,
"activationDate": "2021-09-22T15:55:10Z",
"deactivationDate": null,
"dataloggerId": "240.196164",
"isOnline": true
}

Example for a datalogger (Gen24 Pilot)

{
"deviceType": "Datalogger",
"deviceId": "6f6c6978-2574-2e30-3524-2d3830363933",
"deviceName": "Datalogger",
"deviceManufacturer": "Fronius",
"firmware": {

API Reference– 53
 [Link] Query API manual

"updateAvailable": null,
"installedVersion": null,
"availableVersion": null
},
"isActive": true,
"activationDate": "2020-01-11T1100:00Z",
"deactivationDate": null,
"dataloggerId": "pilot-0.5d-80697371431225991_1593083600",
"isOnline": true
}

Example for an Ohmpilot

{
"deviceType": "Ohmpilot",
"deviceId": "be3dac1d-8c30-4e0a-ae88-2649407cb593",
"deviceName": "Ohmpilot",
"deviceManufacturer": "Fronius",
"serialNumber": "27193272",
"firmware": {
"updateAvailable": true,
"installedVersion": "4000000051",
"availableVersion": "[Link]"
},
"isActive": false,
"activationDate": null,
"deactivationDate": "2017-08-16T17:05:01Z",
"dataloggerId": "240.196164",
"sensors": [
{
"sensorName": "Temperature",
"sensorType": null,
"isActive": true,
"activationDate": null,
"deactivationDate": null
}
]
}

Example for a Wattpilot

{
"deviceType": "EVCharger",
"deviceId": "cee3e54d-0191-4700-8504-aea000d0d839",
"deviceName": "Car Charger 2 ",
"deviceManufacturer": "Fronius",
"serialNumber": "32719074",
"firmware": {

API Reference– 54
 [Link] Query API manual

"updateAvailable": false,
"installedVersion": null,
"availableVersion": null
},
"isActive": true,
"activationDate": "2000-01-01T00:00:00Z",
"deactivationDate": null,
"dataloggerId": "240.196164",
"isOnline": true
}

Example for a battery

{
"deviceType": "Battery",
"deviceId": "68f9a0d4-c50a-43e7-84b0-11c81ef98657",
"deviceName": "",
"deviceManufacturer": "Fronius",
"serialNumber": "25441120",
"capacity": 9600,
"dataloggerId": "239.34376",
"maxChargePower": 6656,
"maxDischargePower": 6656,
"maxSOC": 100,
"minSOC": 0,
"firmware": {
"updateAvailable": false,
"installedVersion": "",
"availableVersion": ""
},
"isActive": true,
"activationDate": "2023-05-29T11:30:41Z",
"deactivationDate": null
}

Example for a Smart Meter

{
"deviceType": "SmartMeter",
"deviceId": "957d94d1-229c-4fab-be84-f06e21c8811a",
"deviceName": "METER_CAT_OTHER",
"deviceManufacturer": "",
"deviceCategory": "Primary Meter",
"deviceLocation": "Grid",
"serialNumber": "",
"dataloggerId": "239.14294",
"firmware": {
"updateAvailable": false,

API Reference– 55
 [Link] Query API manual

"installedVersion": "",
"availableVersion": ""
},
"isActive": true,
"activationDate": null,
"deactivationDate": null
}

Example for multiple devices (of a GEN24 PV system)

{
"devices": [
{
"deviceType": "Inverter",
"deviceId": "6ac1b645-9210-48ac-b6ec-34e6df517dd9",
"deviceName": "Symo GEN24 10.0",
"deviceManufacturer": "Fronius",
"serialNumber": "31393232",
"deviceTypeDetails": "Symo GEN24 10.0 Plus",
"dataloggerId": "pilot-0.5d-80697371430285991_1593083345",
"nodeType": 254,
"numberMPPTrackers": 2,
"numberPhases": 3,
"peakPower": {
"dc1": 7680.0,
"dc2": 2560.0
},
"nominalAcPower": 10000.0,
"firmware": {
"updateAvailable": false,
"installedVersion": null,
"availableVersion": "fro27372"
},
"isActive": true,
"activationDate": "2020-07-14T00:00:00Z",
"deactivationDate": null
},
{
"deviceType": "Battery",
"deviceId": "3ad0653b-7a19-4884-b668-088b9ce9181c",
"deviceName": "",
"deviceManufacturer": "BYD",
"serialNumber": "P030T020Z1912231837",
"dataloggerId": "pilot-0.5d-80697371430285991_1593083345",
"capacity": 22464,
"firmware": {
"updateAvailable": false,
"installedVersion": "",
"availableVersion": ""
},

API Reference– 56
 [Link] Query API manual

"isActive": true,
"activationDate": null,
"deactivationDate": null
},
{
"deviceType": "SmartMeter",
"deviceId": "f0926c18-c254-4ccc-ae59-9d28cbf0896a",
"deviceName": "PowerMeter",
"deviceManufacturer": "Fronius",
"deviceCategory": "Primary Meter",
"deviceLocation": "Grid",
"serialNumber": "17410258",
"dataloggerId": "pilot-0.5d-80697371430285991_1593083345",
"firmware": {
"updateAvailable": false,
"installedVersion": "",
"availableVersion": ""
},
"isActive": true,
"activationDate": "2019-03-25T00:00:00Z",
"deactivationDate": null
},
{
"deviceType": "Ohmpilot",
"deviceId": "6b108c81-d378-46a1-aeba-9a151435c4cb",
"deviceName": "Ohmpilot",
"deviceManufacturer": "Fronius",
"serialNumber": "29209059",
"firmware": {
"updateAvailable": true,
"installedVersion": "[Link]",
"availableVersion": "[Link]"
},
"isActive": true,
"activationDate": "2019-03-25T00:00:00Z",
"deactivationDate": null,
"dataloggerId": "pilot-0.5d-80697371430285991_1593083345",
"sensors": [
{
"sensorName": "Temperature",
"sensorType": null,
"isActive": true,
"activationDate": null,
"deactivationDate": null
}
]
},
{
"deviceType": "Datalogger",
"deviceId": "6f6c6970-2d74-2e30-3564-2d3830363937",
"deviceName": "Datalogger",
"deviceManufacturer": "Fronius",
"firmware": {

API Reference– 57
 [Link] Query API manual

"updateAvailable": null,
"installedVersion": null,
"availableVersion": null
},
"isActive": true,
"activationDate": "2020-07-11T07:00:01Z",
"deactivationDate": null,
"dataloggerId": "pilot-0.5d-80697371430285991_1593083345",
"isOnline": true
}
]
}

Smart Meter categories:

deviceLocation deviceCategory
• AC battery • AC storage unit
• External • Building services
• Generation meter • Climate control / cooling systems
• Grid • Combined heat and power station (CHP)
• Load meter • Electric vehicle
• Sub meter • Heat pump
• LGC Meter
• Other
• Other heating system
• Photovoltaic inverter
• Photovoltaic inverter + storage unit
• Primary Meter
• Pumps
• White goods
• Wind turbine
Sensor types:

sensorType
• Energy
• Insolation
• Irradiation
• Precipitation
• Temperature
• Velocity

API Reference– 58
 [Link] Query API manual

6.3.5 Metadata: Count devices

Use cases for web developers
• I want to know how many devices a specific PV systems has. (Needed for subsequent
enumeration and detail calls.)
• I want to know how many devices I need to show in the UI, so I can prepare memory and
pagination.

Methods

End point and

Method Event name Description
objects
GET /pvsystems/{pv- GetDeviceCount Returns the count of all devices for a
system-id}/ given PV system.
devices-count

Filters and parameters

Filter Description
?type=<devicetype> Type filter - one or more (comma separated, no spaces)
types of devices whose messages should be shown:
• inverter
• sensor
• battery
• smartmeter
• ohmpilot
• datalogger
• evcharger
?isActive=<state> Filters for active (isActive=true) or inactive (isActive=false)
devices only.

Example calls

GET [Link]/pvsystems/20bb600e-019b-4e03-9df3-a0a900cda689/devices-count
// counts all devices in the given PV system

GET [Link]/pvsystems/20bb600e-019b-4e03-9df3-a0a900cda689/devices-count?
type=smartmeter,ohmpilot
// counts all Smart Meter and Ohmpilot devices in the given PV system

Response objects

API Reference– 59
 [Link] Query API manual

JSON object answer construction:

Type Objects
n/a • count (Number)

Example responses

{
"count": 4
}

6.3.6 Metadata: Enumerate device IDs

Use cases for web developers
• I want to enumerate all devices a specific PV system has. With the IDs I can scan these
devices in subsequent calls.

Methods

End point and

Method Event name Description
objects
GET /pvsystems/{pv- GetDeviceIdList Returns the IDs of devices in a PV
system-id}/ system. Filters allow pagination and
devices-list filtering of device types.

Filters and parameters

Filter Description
?offset=<offset>&limit=<limit> Supports pagination, returns devices from a starting
<offset> and returning not more than <limit> items.
?type=<devicetype> Type filter - one or more (comma separated, no spaces)
types of devices whose messages should be shown:
• inverter
• sensor
• battery
• smartmeter
• ohmpilot
• datalogger
• evcharger

API Reference– 60
 [Link] Query API manual

Filter Description
?isActive=<state> Filters for active (isActive=true) or inactive
(isActive=false) devices only.

Example calls

GET [Link]/pvsystems/20bb600e-019b-4e03-9df3-a0a900cda689/devices-list
// returns the device IDs of all devices in the given PV system

GET [Link]/pvsystems/20bb600e-019b-4e03-9df3-a0a900cda689/devices-list?
type=inverter,sensor,battery
// returns the device IDs of all inverters, sensors and batteries in the given PV
system

GET [Link]/pvsystems/20bb600e-019b-4e03-9df3-a0a900cda689/devices-list?
offset=0&limit=5
// returns the device IDs of the first five devices in the given PV system

Response objects

JSON object answer construction:

Type Objects
n/a • deviceIds (Array of Strings)

Example responses

{
"deviceIds": [
"52a44bc2-3697-4339-9437-6d077c44aac4",
"58099f2e-56ab-415f-bcc4-a1d400ccbf56",
"6e089afa-280f-483d-b4f1-a1d600ae2582",
"fbd0af74-6b5b-4a02-bd32-8f91447225ae",
"9df7c03d-e008-42f8-8ad2-a1d400ccbf2c",
"ddef5593-76f6-41e4-9e4d-a1d400ccbf15",
"675570a3-7395-43d9-a45e-ffc4c5bf5390",
"6f1361c7-2003-4380-b2d5-d78645bcb07e",
"0a8a3b70-ae7e-4e7c-82f2-9007ce65b8ba"
]
}

API Reference– 61
 [Link] Query API manual

6.4 Aggregation calls

This set contains methods to retrieve the energy production and consumption values of a PV
system, aggregated over the whole lifetime, years, months, and/or days.

From these you can create diagrams like the following one:

6.4.1 Aggrdata: Aggregated energy data for a PV system

Use cases for web developers
• I want to show total/lifetime aggregated energy values to an end user.
• I want to show annually, monthly or daily aggregated energy values to an end user.
• I want to show aggregated energy values to an end user, but for custom time periods (e.g. a
week or last 6 months).

Methods

API Reference– 62
 [Link] Query API manual

Method End point and objects Event name Description

GET /pvsystems/{pv-system- GetSystemAggregate Gets aggregated data for a given
id}/aggrdata dData PV system for a custom period of
time. The custom period can either
span years, months, or days.
The data is returned as a JSON
object.
Filters allow limiting to specific PV
system energy values.

Filters and parameters

Filter Description
?channel=<channel> One or more of the detail data channels.
Channel filters can be concatenated using commas.
E.g.: ?channel=EnergyFeedIn,EnergyPurchased
?from=<start>&to=<end> Limits the time series for the query.
Period types in <from> and <to> need to match (i.e. both
need to be either years, months, or days).
Encoding:
• yyyy for years
• yyyy-MM or yyyyMM for months
• yyyy-MM-dd or yyyyMMdd for days
?from=<start>&duration=<length> Limits the time series for the query.
<duration> is measured in years, months or days -
depending on the <from> parameter.
A <duration> of 1 means that start and end are equal.
Encoding:
• yyyy for years
• yyyy-MM or yyyyMM for months
• yyyy-MM-dd or yyyyMMdd for days

API Reference– 63
 [Link] Query API manual

Filter Description
?period=<period> Limits the time series for the query to a period.
Encoding:
• "total" delivers total values over whole system
lifetime
• "years" delivers values for each year of system
lifetime
• yyyy delivers all months of requested year
• yyyy-MM delivers all days of requested month
Note: If <period> parameter is used, then <from>, <to>
and <duration> parameters are not allowed, and vice
versa.
?offset=<offset>&limit=<limit> Supports pagination, returns items from a starting
<offset> and returning not more than <limit> items
(items = objects in the "Data" array).

Example calls

GET [Link]/pvsystems/20bb600e-019b-4e03-9df3-a0a900cda689/aggrdata?
period=total
// get aggregated total energy flow values of this system for total lifetime

GET [Link]/pvsystems/20bb600e-019b-4e03-9df3-a0a900cda689/aggrdata?
period=years
// get aggregated annual energy flow values of this system for all years since the
installation

GET [Link]/pvsystems/20bb600e-019b-4e03-9df3-a0a900cda689/aggrdata?
from=2017&duration=1
// get the aggregated annual energy flow values of this system for 2017

GET [Link]/pvsystems/20bb600e-019b-4e03-9df3-a0a900cda689/aggrdata?
period=2017
// get the aggregated monthly energy flow values of this system for 2017

GET [Link]/pvsystems/20bb600e-019b-4e03-9df3-a0a900cda689/aggrdata?
from=2017-12&duration=1
// get the aggregated monthly energy flow values of this system for December 2017

GET [Link]/pvsystems/20bb600e-019b-4e03-9df3-a0a900cda689/aggrdata?
period=2017-12
// get the aggregated daily energy flow values of this system for December 2017

GET [Link]/pvsystems/20bb600e-019b-4e03-9df3-a0a900cda689/aggrdata?
from=2017-12-01&to=2017-12-31
// get the aggregated daily energy flow values of this system for December 2017
(alternative to above)

API Reference– 64
 [Link] Query API manual

GET [Link]/pvsystems/20bb600e-019b-4e03-9df3-a0a900cda689/aggrdata?
from=2017-12-01&duration=31
// get the aggregated daily energy flow values of this system for December 2017
(alternative to above)

GET [Link]/pvsystems/20bb600e-019b-4e03-9df3-a0a900cda689/aggrdata?
from=2017-12-24&duration=1
// get the aggregated daily energy flow values of this system for December 24, 2017

GET [Link]/pvsystems/20bb600e-019b-4e03-9df3-a0a900cda689/aggrdata?
from=2017-12-24&duration=7
// get the aggregated daily energy flow values of this system for the week December
24-30, 2017

GET [Link]/pvsystems/20bb600e-019b-4e03-9df3-a0a900cda689/aggrdata?
from=2017-12&duration=1&channel=EnergyFeedIn
// get the EnergyFeedIn value of this system for December 2017

GET [Link]/pvsystems/20bb600e-019b-4e03-9df3-a0a900cda689/aggrdata?
from=2017-12&duration=1&channel=EnergyBattCharge,EnergyBattDischarge
// get the EnergyBattCharge and EnergyBattDischarge values of this system for
December 2017

GET [Link]/pvsystems/20bb600e-019b-4e03-9df3-a0a900cda689/aggrdata?
from=2017-01-01&duration=365&channel=EnergyFeedIn&limit=7
// get the EnergyFeedIn values of this system for all days of the year 2017, in
weekly pages

Response objects

JSON object answer construction:

Objects
• pvSystemID
• data
• logDate (String - date information like "yyyy", "yyyy-MM" or "yyyy-MM-dd", or "total")
• channels (Array)
• channelName (String)
• channelType (String)
• unit (String)
• value (Number)

Supported value channels

API Reference– 65
 [Link] Query API manual

Type Channels Comment

PV system • EnergyFeedIn Requires Smart Meter; otherwise NULL
energy flow • EnergyPurchased
with Smart • EnergySelfConsumption
Meter • EnergyDirectConsumption
• EnergyBattCharge Requires Smart Meter and battery;
• EnergyBattDischarge otherwise NULL
• EnergyBattChargeGrid
• EnergyBattDischargeGrid
• OhmpilotEnergy Uses [Link],
NOT OhmPilotEnergy!
Requires Smart Meter and Ohmpilot;
otherwise NULL
• EnergyEVCCharge Requires Smart Meter and Wattpilot;
• EnergyEVCChargeGrid otherwise NULL
• EnergyEVCChargeBatt
PV system • EnergyOutput Only if there is no Smart Meter; NULL with
output Smart Meter
without
Smart Meter
PV system • EnergyProductionTotal Requires Smart Meter; otherwise NULL
totals • EnergyConsumptionTotal
• EnergySelfConsumptionTotal
PV system • SavingsCO2
CO2 savings • SavingsTrees
• SavingsTravelCar
• SavingsTravelPlane
PV system • Profits Requires profit settings in [Link];
savings • Earnings otherwise NULL
• Savings

Example responses

Example for retrieving all channels for total lifetime

{
"pvSystemId": "20bb600e-019b-4e03-9df3-a0a900cda689",
"data": [
{

API Reference– 66
 [Link] Query API manual

"logDateTime": "total",
"channels": [
{
"channelName": "SavingsCO2",
"channelType": "CO2 savings",
"unit": "kg",
"value": 539552.54
},
{
"channelName": "SavingsTrees",
"channelType": "CO2 savings",
"unit": "tree",
"value": 13834.68
},
{
"channelName": "SavingsTravelCar",
"channelType": "CO2 savings",
"unit": "km",
"value": 3597016.94
},
{
"channelName": "SavingsTravelPlane",
"channelType": "CO2 savings",
"unit": "mile",
"value": 1798508.46
},
{
"channelName": "Profits",
"channelType": "Currency",
"unit": "EUR",
"value": 11616.8943
},
{
"channelName": "Earnings",
"channelType": "Currency",
"unit": "EUR",
"value": 14276.4026
},
{
"channelName": "Savings",
"channelType": "Currency",
"unit": "EUR",
"value": 8985.9121
},
{
"channelName": "EnergyOutput",
"channelType": "Energy",
"unit": "Wh",
"value": 10880386.5320
},
{
"channelName": "EnergyBattDischarge",
"channelType": "Energy",

API Reference– 67
 [Link] Query API manual

"unit": "Wh",
"value": 12869207.6682
},
{
"channelName": "EnergyBattDischargeGrid",
"channelType": "Energy",
"unit": "Wh",
"value": 143905.5845
},
{
"channelName": "EnergyBattCharge",
"channelType": "Energy",
"unit": "Wh",
"value": 14609870.0412
},
{
"channelName": "EnergySelfConsumption",
"channelType": "Energy",
"unit": "Wh",
"value": 35305418.9650
},
{
"channelName": "EnergyFeedIn",
"channelType": "Energy",
"unit": "Wh",
"value": 44585679.6562
},
{
"channelName": "EnergyBattChargeGrid",
"channelType": "Energy",
"unit": "Wh",
"value": 69769.6105
},
{
"channelName": "EnergyPurchased",
"channelType": "Energy",
"unit": "Wh",
"value": 27991985.4892
},
{
"channelName": "EnergyEVCChargeGrid",
"channelType": "Energy",
"unit": "Wh",
"value": 0.0
}, {
"channelName": "EnergyProductionTotal",
"channelType": "Energy",
"unit": "Wh",
"value": 94500968.6624
},
{
"channelName": "EnergySelfConsumptionTotal",
"channelType": "Energy",

API Reference– 68
 [Link] Query API manual

"unit": "Wh",
"value": 49915289.0062
},
{
"channelName": "EnergyConsumptionTotal",
"channelType": "Energy",
"unit": "Wh",
"value": 77907274.4954
}
]
}
]
}

Example for retrieving the EnergySelfConsumption channel for multiple years

{
"pvSystemId": "20bb600e-019b-4e03-9df3-a0a900cda689",
"data": [
{
"logDateTime": "2014",
"channels": [
{
"channelName": "EnergySelfConsumption",
"channelType": "Energy",
"unit": "Wh",
"value": 4710304.1779
}
]
},
{
"logDateTime": "2015",
"channels": [
{
"channelName": "EnergySelfConsumption",
"channelType": "Energy",
"unit": "Wh",
"value": 5678721.3691
}
]
},
{
"logDateTime": "2016",
"channels": [
{
"channelName": "EnergySelfConsumption",
"channelType": "Energy",
"unit": "Wh",
"value": 9511044.7487
}

API Reference– 69
 [Link] Query API manual

]
}
]
}

Example for retrieving the EnergySelfConsumption channel for a week

{
"pvSystemId": "20bb600e-019b-4e03-9df3-a0a900cda689",
"data": [
{
"logDateTime": "2020-06-29",
"channels": [
{
"channelName": "EnergySelfConsumption",
"channelType": "Energy",
"unit": "Wh",
"value": 24612.0087
}
]
},
{
"logDateTime": "2020-06-30",
"channels": [
{
"channelName": "EnergySelfConsumption",
"channelType": "Energy",
"unit": "Wh",
"value": 23861.9769
}
]
},
{
"logDateTime": "2020-07-01",
"channels": [
{
"channelName": "EnergySelfConsumption",
"channelType": "Energy",
"unit": "Wh",
"value": 23267.4185
}
]
},
{
"logDateTime": "2020-07-02",
"channels": [
{
"channelName": "EnergySelfConsumption",
"channelType": "Energy",
"unit": "Wh",

API Reference– 70
 [Link] Query API manual

"value": 28923.5102
}
]
},
{
"logDateTime": "2020-07-03",
"channels": [
{
"channelName": "EnergySelfConsumption",
"channelType": "Energy",
"unit": "Wh",
"value": 30986.6525
}
]
},
{
"logDateTime": "2020-07-04",
"channels": [
{
"channelName": "EnergySelfConsumption",
"channelType": "Energy",
"unit": "Wh",
"value": 18682.0911
}
]
},
{
"logDateTime": "2020-07-05",
"channels": [
{
"channelName": "EnergySelfConsumption",
"channelType": "Energy",
"unit": "Wh",
"value": 20237.0875
}
]
}
]
}

6.4.2 Aggrdata: Aggregated energy data for a device

Use cases for web developers
• I want to show an inverter's total/lifetime aggregated energy values to an end user.
• I want to show an inverter's annually, monthly or daily aggregated energy values to an end
user.
• I want to show an inverter's aggregated energy values to an end user, but for custom time
periods (e.g. a week or last 6 months).

API Reference– 71
 [Link] Query API manual

Methods

Method End point and objects Event name Description

GET /pvsystems/{pv- GetDeviceAggregated Gets aggregated data for a given
system-id}/devices/ Data device of a given PV system for a
{device-id}/aggrdata custom period of time. The custom
period can either span years,
months, or days.
The data is returned as a JSON
object.

Filters and parameters

Filter Description
?channel=<channel> One or more of the detail data channels.
?from=<start>&to=<end> Limits the time series for the query.
Period types in <from> and <to> need to match (i.e. both
need to be either years, months, or days).
Encoding:
• yyyy for years
• yyyy-MM or yyyyMM for months
• yyyy-MM-dd or yyyyMMdd for days
?from=<start>&duration=<length> Limits the time series for the query.
<Duration> is measured in years, months or days -
depending on the <from> parameter.
A <duration> of 1 means that start and end are equal.
Encoding:
• yyyy for years
• yyyy-MM or yyyyMM for months
• yyyy-MM-dd or yyyyMMdd for days
?period=<period> Limits the time series for the query to a period.
Encoding:
• "total" delivers total values over whole system
lifetime
• "years" delivers values for each year of system
lifetime
• yyyy delivers all months of requested year
• yyyy-MM delivers all days of requested month
Note: If <period> parameter is used, then <from>, <to>
and <duration> parameters are not allowed, and vice
versa.

API Reference– 72
 [Link] Query API manual

Filter Description
?offset=<offset>&limit=<limit> Supports pagination, returns items from a starting
<offset> and returning not more than <limit> items
(items = objects in the "Data" array).

Example calls

GET [Link]/pvsystems/20bb600e-019b-4e03-9df3-a0a900cda689/devices/
b582f1b9-95b9-49db-800b-6b042e9938b4/aggrdata?from=2010&to=2015
// get aggregated annual energy values of this device for the years 2010 to 2015

GET [Link]/pvsystems/20bb600e-019b-4e03-9df3-a0a900cda689/devices/
b582f1b9-95b9-49db-800b-6b042e9938b4/aggrdata?from=2020-02-24&duration=7
// get aggregated daily energy values of this device for the week of February 24th
to March 1st, 2020

GET [Link]/pvsystems/20bb600e-019b-4e03-9df3-a0a900cda689/devices/
b582f1b9-95b9-49db-800b-6b042e9938b4/aggrdata?period=total
// get aggregated energy values of this device for its total lifetime

GET [Link]/pvsystems/20bb600e-019b-4e03-9df3-a0a900cda689/devices/
b582f1b9-95b9-49db-800b-6b042e9938b4/aggrdata?period=years
// get aggregated annual energy values of this device for all years since the
installation

GET [Link]/pvsystems/20bb600e-019b-4e03-9df3-a0a900cda689/devices/
b582f1b9-95b9-49db-800b-6b042e9938b4/aggrdata?from=2017&duration=1
// get aggregated annual energy values of this device for the year 2017

GET [Link]/pvsystems/20bb600e-019b-4e03-9df3-a0a900cda689/devices/
b582f1b9-95b9-49db-800b-6b042e9938b4/aggrdata?period=2017
// get aggregated monthly energy values of this device for 2017

GET [Link]/pvsystems/20bb600e-019b-4e03-9df3-a0a900cda689/devices/
b582f1b9-95b9-49db-800b-6b042e9938b4/aggrdata?from=2017-12&duration=1
// get aggregated monthly energy values of this device for the month December 2017

GET [Link]/pvsystems/20bb600e-019b-4e03-9df3-a0a900cda689/devices/
b582f1b9-95b9-49db-800b-6b042e9938b4/aggrdata?period=2017-12
// get aggregated daily energy values of this device for December 2017

GET [Link]/pvsystems/20bb600e-019b-4e03-9df3-a0a900cda689/devices/
b582f1b9-95b9-49db-800b-6b042e9938b4/aggrdata?from=2017-12-01&to=2017-12-31
// get aggregated daily energy values of this device for December 2017 (alternative
to above)

GET [Link]/pvsystems/20bb600e-019b-4e03-9df3-a0a900cda689/devices/
b582f1b9-95b9-49db-800b-6b042e9938b4/aggrdata?from=2017-12-01&duration=31
// get aggregated daily energy values of this device for December 2017 (alternative
to above)

API Reference– 73
 [Link] Query API manual

GET [Link]/pvsystems/20bb600e-019b-4e03-9df3-a0a900cda689/devices/
b582f1b9-95b9-49db-800b-6b042e9938b4/aggrdata?from=2017-12-24&duration=1
// get aggregated daily energy values of this device for the day of December 24,
2017

GET [Link]/pvsystems/20bb600e-019b-4e03-9df3-a0a900cda689/devices/
b582f1b9-95b9-49db-800b-6b042e9938b4/aggrdata?from=2017-12-24&duration=7
// get aggregated daily energy values of this device for the week December 24-30,
2017

GET [Link]/pvsystems/20bb600e-019b-4e03-9df3-a0a900cda689/devices/
b582f1b9-95b9-49db-800b-6b042e9938b4/aggrdata?from=2017-12&duration=1
// get aggregated energy values of this device for the month of December 2017

Response objects

JSON object answer construction:

Objects
• pvSystemID
• deviceID
data
• logDate (String - date information like "yyyy", "yyyy-MM" or "yyyy-MM-dd", or "total")
• channels (Array)
• channelName (String)
• channelType (String)
• unit (String)
• value (Number)

Supported channels:

API Reference– 74
 [Link] Query API manual

Type Channels
Inverter • EnergyExported
• EnergyDC1
• EnergyDC2
• ...

New inverter types can

have more than two
strings. If there are more
than two strings, their
energy channels will be
added as
"EnergyDCn" (where n is
the number of the
string).

Example responses

{
"pvSystemId": "20bb600e-019b-4e03-9df3-a0a900cda689",
"deviceId": "b582f1b9-95b9-49db-800b-6b042e9938b4",
"data": [
{
"logDateTime": "total",
"channels": [
{
"channelName": "EnergyExported",
"channelType": "Energy",
"unit": "Wh",
"value": 32154.3471
},
{
"channelName": "EnergyDC1",
"channelType": "Energy",
"unit": "Wh",
"value": 155055.7984
},
{
"channelName": "EnergyDC2",
"channelType": "Energy",
"unit": "Wh",
"value": 0.0
}
]
}

API Reference– 75
 [Link] Query API manual

]
}

API Reference– 76
 [Link] Query API manual

6.5 Historical data calls

This set contains methods to retrieve the historical data for a PV system or for a single device of a
given PV system.

Historical data points are data points that are logged at the inverter and transferred to [Link]
at regular intervals (usually every hour). By default the resolution of these data points is 5 minutes.
Please note that power values are logged as energy values. To calculate power values from energy
values (to display curves as shown below) please refer to section Best practices and how-tos at the
end of this document.

With the historical data you can create diagrams like this one:

6.5.1 Histdata: Historical data for a PV system

Use cases for web developers
• I want to show time series graphs for a complete PV system.

Restrictions

Impersonated basic users can only retrieve information not older than 72 hours - like in [Link].

API Reference– 77
 [Link] Query API manual

Inverters report production data to [Link] only once per hour. Data channels for the current
hour therefore cannot be accessed by applications.

Methods

End point and

Method Event name Description
objects
GET /pvsystems/{pv- GetSystemHistoricalDa Gets historical data for a given PV
system-id}/ ta system and time range. The data
histdata resolution is 5min.
The data is returned a JSON object.

Filters and parameters

Filter Description
?channel=<channel> One of the detail data channels from inverter, sensor,
battery, Smart Meter, Ohmpilot, or general type
categories.
?timezone=<"local", "zulu"> Specifies time format in response object:
• zulu (default): returns time in UTC zulu time.
• local: returns time in PV system's local UTC time (local
time + UTC offset).
?from=<start>&to=<end> Limits the time series for the query.
• <start> and <end> are ISO-8601 time values.
• Time format encoding:
"yyyyMMddTHHmmssTZD", "yyyy-MM-
ddTHH:mm:ssTZD".
?offset=<offset>&limit=<limit> Supports pagination, returns items from a starting
<offset> and returning not more than <limit> items (items
= objects in the "Data" array).

Example calls

GET [Link]/pvsystems/20bb600e-019b-4e03-9df3-a0a900cda689/histdata?
from=2018-10-10T00:00:00Z&to=2018-10-11T00:00:00Z
// gets all historical values for 10th of October, 2018, for PV system

Response objects

JSON object answer construction:

API Reference– 78
 [Link] Query API manual

Objects
• pvSystemId (String)
• data (Array)
• logDateTime (UTC Time)
• logDuration (Integer - unit: seconds)
• channels (Array)
• channelName (String)
• channelType (String)
• unit (String)
• value (Number, String)

Supported value channels:

Type Objects Remarks

PV system • EnergyFeedIn Requires Smart Meter; otherwise NULL
power flow • EnergyPurchased
with Smart • EnergySelfConsumption
Meter • EnergyBattCharge Requires Smart Meter and battery;
• EnergyBattChargeGrid otherwise NULL
• EnergyBattDischarge
• EnergyBattDischargeGrid
• EnergyEVCCharge Requires Smart Meter and EV charger;
• EnergyEVCChargeBatt otherwise NULL
• EnergyEVCChargeGrid
PV system • EnergyOutput Only if there is no Smart Meter; NULL with
power flow Smart Meter
without
Smart Meter
PV system • EnergyProductionTotal
totals • EnergyConsumptionTotal
• EnergySelfConsumptionTotal
• EnergyEVCChargeTotal

Example responses

{
"pvSystemId": "73733052-6f10-47a5-9746-7f7e76ebcb8c",
"deviceId": null,
"data": [
{
"logDateTime": "2022-06-27T10:00:00Z",

API Reference– 79
 [Link] Query API manual

"logDuration": 599,
"channels": [
{
"channelName": "EnergySelfConsumption",
"channelType": "Energy",
"unit": "Wh",
"value": 0.0
},
{
"channelName": "EnergyFeedIn",
"channelType": "Energy",
"unit": "Wh",
"value": 0.0
},
{
"channelName": "EnergyBattCharge",
"channelType": "Energy",
"unit": "Wh",
"value": 0.0
},
{
"channelName": "EnergyBattDischargeGrid",
"channelType": "Energy",
"unit": "Wh",
"value": 0.0
},
{
"channelName": "EnergyBattDischarge",
"channelType": "Energy",
"unit": "Wh",
"value": 0.0
},
{
"channelName": "EnergyPurchased",
"channelType": "Energy",
"unit": "Wh",
"value": 14.02
},
{
"channelName": "EnergyBattChargeGrid",
"channelType": "Energy",
"unit": "Wh",
"value": 0.0
},
{
"channelName": "EnergyOutput",
"channelType": "Energy",
"unit": "Wh",
"value": 0.0
},
{
"channelName": "EnergyEVCCharge",
"channelType": "Energy",
"unit": "Wh",

API Reference– 80
 [Link] Query API manual

"value": 0.0
},
{
"channelName": "EnergyEVCChargeBatt",
"channelType": "Energy",
"unit": "Wh",
"value": 0.0
},
{
"channelName": "EnergyEVCChargeGrid",
"channelType": "Energy",
"unit": "Wh",
"value": 0.0
},
{
"channelName": "EnergyProductionTotal",
"channelType": "Energy",
"unit": "Wh",
"value": 0.0
},
{
"channelName": "EnergySelfConsumptionTotal",
"channelType": "Energy",
"unit": "Wh",
"value": 0.0
},
{
"channelName": "EnergyConsumptionTotal",
"channelType": "Energy",
"unit": "Wh",
"value": 14.02
},
{
"channelName": "EnergyEVCChargeTotal",
"channelType": "Energy",
"unit": "Wh",
"value": 0.0
}
]
}
]
}

6.5.2 Histdata: Historical data for a device

Use cases for web developers
• I want to show time series graphs for a PV system, but only for a certain type or device
(inverters, sensors, batteries, smartmeters, ohmpilots).

API Reference– 81
 [Link] Query API manual

Restrictions

Impersonated basic users can only retrieve information not older than 72 hours - like in [Link].

Inverters report production data to [Link] only once per hour. Data channels for the current
hour therefore cannot be accessed by applications.

Methods

End point and

Method Event name Description
objects
GET /pvsystems{pv- GetDeviceHistoricalDat Gets historical data for a given PV
system-id}/ a device of a given PV system and time
devices/{device- range. The data resolution is 5 min.
id}/histdata The data is returned a JSON object.

Filters and parameters

Filter Description
?channel=<channel> One of the detail data channels.
?timezone=<"local", "zulu"> Specifies time format in response object:
• zulu (default): returns time in UTC zulu time.
• local: returns time in PV system's local UTC time (local
time + UTC offset).
?from=<start>&to=<end> Limits the time series for the query.
• <start> and <end> are ISO-8601 time values.
• Time format encoding:
"yyyyMMddTHHmmssTZD", "yyyy-MM-
ddTHH:mm:ssTZD".
?offset=<offset>&limit=<limit> Supports pagination, returns items from a starting
<offset> and returning not more than <limit> items (items
= objects in the "Data" array).

Example calls

GET [Link]/pvsystems/20bb600e-019b-4e03-9df3-a0a900cda689/devices/
d2e61bf2-8dd7-4ba1-8733-d55d738c4679/histdata?from=2018-10-10T00:00:00Z&to=2018-10-11
T00:00:00Z
// gets all historical values for 10th of October, 2018, for given device

API Reference– 82
 [Link] Query API manual

GET [Link]/pvsystems/20bb600e-019b-4e03-9df3-a0a900cda689/devices/
d2e61bf2-8dd7-4ba1-8733-d55d738c4679/histdata?
from=20181010T000000Z&to=20181011T000000Z?channel=Temp1
// gets all historical temperature values (Temp1 channel) for the 10th of October,
2018, for given device

Response objects

JSON object answer construction:

Objects
• pvSystemId (String)
• deviceId (String)
• data (Array)
• logDateTime (UTC Time)
• logDuration (Integer - unit: seconds)
• channels (Array)
• channelName (String)
• channelType (String)
• unit (String)
• value (Number or String, depending on channel)
Supported channels:

API Reference– 83
 [Link] Query API manual

Type Channels Type Channels

Inverter • EnergyExported Smart Meter • GridPowerA
• EnergyImported • GridPowerB
• EnergyDC1 • GridPowerC
• EnergyDC2 • GridApparentPowerA
• ... • GridApparentPowerB
• GridApparantPowerC
New inverter types can • GridVoltageA
have more than two • GridVoltageB
strings. If there are • GridVoltageC
more than two strings, • LoadPowerA
their "EnergyDCn", • LoadPowerB
"CurrentDCn" and • LoadPowerC
"VoltageDCn" channels • LoadApparentPowerA
will be added (where n is • LoadApparentPowerB
the number of the • LoadApparentPowerC
string). • LoadVoltageA
• LoadVoltageB
• CurrentA
• LoadVoltageC
• CurrentB
• ExtEnergyExportedAbs
• CurrentC
• ExtEnergyExported
• CurrentDC1
• EnergyLoadAbs
• CurrentDC2
• EnergyLoad
• ...
• EnergyImported
• VoltageA
• EnergyExported
• VoltageB
• GridEnergyExportedAbs
• VoltageC
• GridEnergyImportedAbs
• VoltageAB
• GridEnergyExported
• VoltageBC
• GridEnergyImported
• VoltageCA
• VoltageDC1
• VoltageDC2
• ...
• ApparentPower
• ReactivePower
• PowerFactor
• StandardizedPower

API Reference– 84
 [Link] Query API manual

Type Channels
Sensor • Temp1
• Temp2
• Insolation
• Digital1
• Digital2
• Digital3
• Digital1Energy
• Digital2Energy
• Digital3Energy
Battery • BattOpState
• BattSOC
Ohmpilot • OhmpilotTemp
• OhmpilotEnergyAbs
• OhmpilotEnergy
• OhmpilotError
EV charger • EnergyChargeTotal
• VoltageA
• VoltageB
• VoltageC

Example responses

Inverter

{
"pvSystemId": "85896da3-bb2a-47f7-9c6e-2909dd44832c",
"deviceId": "ea5e207e-84c0-49fd-a9e0-ed7234a84c63",
"data": [
{
"logDateTime": "2019-07-31T12:00:00Z",
"logDuration": 300,
"channels": [
{
"channelName": "GridEnergyExported",
"channelType": "Energy",
"unit": "Wh",
"value": 313.11
},
{
"channelName": "StandardizedPower",
"channelType": "Percentage",
"unit": "%",
"value": 1.3
},

API Reference– 85
 [Link] Query API manual

{
"channelName": "VoltageA",
"channelType": "Voltage",
"unit": "V",
"value": 236.7
},
{
"channelName": "VoltageB",
"channelType": "Voltage",
"unit": "V",
"value": 226.1
},
{
"channelName": "VoltageC",
"channelType": "Voltage",
"unit": "V",
"value": 238.5
},
{
"channelName": "CurrentA",
"channelType": "Current",
"unit": "A",
"value": 5.37
},
{
"channelName": "CurrentB",
"channelType": "Current",
"unit": "A",
"value": 5.27
},
{
"channelName": "CurrentC",
"channelType": "Current",
"unit": "A",
"value": 5.38
},
{
"channelName": "VoltageDC1",
"channelType": "Voltage",
"unit": "V",
"value": 574.7
},
{
"channelName": "CurrentDC1",
"channelType": "Current",
"unit": "A",
"value": 5.22
},
{
"channelName": "VoltageDC2",
"channelType": "Voltage",
"unit": "V",
"value": 491

API Reference– 86
 [Link] Query API manual

},
{
"channelName": "CurrentDC2",
"channelType": "Current",
"unit": "A",
"value": 1.87
},
{
"channelName": "ReactivePower",
"channelType": "Reactive Power",
"unit": "VAr",
"value": -78.9
},
{
"channelName": "ApparentPower",
"channelType": "Apparent Power",
"unit": "VA",
"value": 3758.15
},
{
"channelName": "PowerFactor",
"channelType": "",
"unit": "",
"value": 1
},
{
"channelName": "EnergyDC1",
"channelType": "Energy",
"unit": "Wh",
"value": 239.72
},
{
"channelName": "EnergyDC2",
"channelType": "Energy",
"unit": "Wh",
"value": 73.39
}
]
}
]
}

Battery

{
"pvSystemId": "85896da3-bb2a-47f7-9c6e-2909dd44832c",
"deviceId": "83129be8-a1ec-48b1-a8a8-7c5accd6b64e",
"data": [
{
"logDateTime": "2019-07-31T12:00:00Z",

API Reference– 87
 [Link] Query API manual

"logDuration": 300,
"channels": [
{
"channelName": "BattSOC",
"channelType": "Percentage",
"unit": "%",
"value": 97
}
]
}
]
}

Smart Meter (primary)

{
"pvSystemId": "85896da3-bb2a-47f7-9c6e-2909dd44832c",
"deviceId": "f2adce80-e9f2-43cb-b6ae-26ab2e39cd8f",
"data": [
{
"logDateTime": "2019-07-31T12:00:00Z",
"logDuration": 300,
"channels": [
{
"channelName": "GridPowerA",
"channelType": "Power",
"unit": "W",
"value": -1323.92
},
{
"channelName": "GridPowerB",
"channelType": "Power",
"unit": "W",
"value": 220.4
},
{
"channelName": "GridPowerC",
"channelType": "Power",
"unit": "W",
"value": -2384.07
},
{
"channelName": "GridApparentPowerA",
"channelType": "Apparent Power",
"unit": "VA",
"value": 1364.11
},
{
"channelName": "GridApparentPowerB",
"channelType": "Apparent Power",

API Reference– 88
 [Link] Query API manual

"unit": "VA",
"value": 1052.78
},
{
"channelName": "GridApparentPowerC",
"channelType": "Apparent Power",
"unit": "VA",
"value": 2411.02
},
{
"channelName": "GridVoltageA",
"channelType": "Voltage",
"unit": "V",
"value": 235.66
},
{
"channelName": "GridVoltageB",
"channelType": "Voltage",
"unit": "V",
"value": 225.61
},
{
"channelName": "GridVoltageC",
"channelType": "Voltage",
"unit": "V",
"value": 237.92
}
]
}
]
}

Smart Meter (consumption)

{
"pvSystemId": "85896da3-bb2a-47f7-9c6e-2909dd44832c",
"deviceId": "d2c78b92-1d96-4fad-93cb-ec43169c3ed0",
"data": [
{
"logDateTime": "2021-01-01T09:00:00Z",
"logDuration": 300,
"channels": [
{
"channelName": "EnergyExported",
"channelType": "Energy",
"unit": "Wh",
"value": 0.0
},
{
"channelName": "EnergyImported",

API Reference– 89
 [Link] Query API manual

"channelType": "Energy",
"unit": "Wh",
"value": 0.0
}
]
}
]
}

Ohmpilot

{
"pvSystemId": "85896da3-bb2a-47f7-9c6e-2909dd44832c",
"deviceId": "17280720-2079-495d-92cb-fa3ce2afa305",
"data": [
{
"logDateTime": "2019-07-31T12:00:00Z",
"logDuration": 300,
"channels": [
{
"channelName": "OhmPilotTemp",
"channelType": "Temperature",
"unit": "°C",
"value": 57.3
},
{
"channelName": "OhmPilotEnergy",
"channelType": "Energy",
"unit": "Wh",
"value": 85
}
]
}
]
}

EV charger

{
"pvSystemId": "73733052-6f10-47a5-9746-7f7e76ebcb8c",
"deviceId": "cee3e54d-0191-4700-8504-aea000d0d839",
"data": [
{
"logDateTime": "2022-08-14T11:00:00+10:00",
"logDuration": 300,
"channels": [
{
"channelName": "EnergyChargeTotal",

API Reference– 90
 [Link] Query API manual

"channelType": "Energy",
"unit": "Wh",
"value": 0.0
},
{
"channelName": "VoltageA",
"channelType": "Voltage",
"unit": "V",
"value": 241.81
},
{
"channelName": "VoltageB",
"channelType": "Voltage",
"unit": "V",
"value": 241.84
},
{
"channelName": "VoltageC",
"channelType": "Voltage",
"unit": "V",
"value": 243.51
}
]
}

]
}

API Reference– 91
 [Link] Query API manual

6.6 Realtime data calls

This set contains methods to retrieve the power flow data for a PV system or for a single device of
a given PV system.

The power flow data points are real time data. The data is updated every few seconds. To make use
of the full potential of the power flow data the PV system is required to have a Fronius Smart
Meter installed. With such a meter [Link] can determine the directions of the power flows (e.g.
to the grid, from the battery, etc.). Without a meter only the power generated by the PV system
can be provided.

Power flows can be shown like in this diagram:

6.6.1 Flowdata: Realtime power flow data of a PV system

Use cases for web developers
• I want to show current power flow for a complete PV system.

Methods

API Reference– 92
 [Link] Query API manual

End point and

Method Event name Description
objects
GET /pvsystems/{pv- GetSystemFlowData Gets the realtime power flow data of a
system-id}/ given PV system.
flowdata The data is returned as a JSON object.

Filters and parameters

Filter Description
?timezone=<"local", "zulu"> Specifies time format in response object:
• zulu (default): returns time in UTC zulu time
• local: returns time in PV system's local UTC time
(local time + UTC offset)

Example calls

GET [Link]/pvsystems/20bb600e-019b-4e03-9df3-a0a900cda689/flowdata
// gets current power flow information for the given PV system

Response objects

JSON object answer construction:

Objects
• pvSystemId (String)
• status
• isOnline (Boolean)
• battMode (Number)
• data
• logDateTime (UTC
time)
• channels (Array)
• channelName
(String)
• channelType
(String)
• unit (String)
• value (Number,
String)

Supported value channels:

API Reference– 93
 [Link] Query API manual

Type Channels Remarks

PV system • PowerFeedIn If a Smart Meter is attached, it provides the
• PowerLoad values for PowerFeedIn, PowerLoad,
• PowerBattCharge PowerBattCharge, PowerOhmpilot,
• PowerOhmpilot PowerPV. PowerOutput will return NULL in
• PowerPV this case. Positive values are going to the
• PowerOutput inverter, negative values from the inverter
• BattSOC to somewhere else.
• RateSelfConsumption If there is no Smart Meter, the inverter
• RateSelfSufficiency returns PowerOutput instead.
• PowerEVCTotal
• PowerBattCharge is negative when
charging
• isOnline when is the system shown online? timeout
• battMode when loosing contact?
which battmodes are available and what do
they mean

Sometimes NULL values are returned, but another call a few seconds later returns valid
data.
This is because [Link] implements an asynchronous architecture. For the powerflow
data [Link] has to request the data from the PV systems' devices. Depending on the
round-trip time it can happen that [Link] internally runs into a timeout while waiting for
the data to be reported from the devices. Hence, SWQAPI then will return no values.
However, the data arrives usually after a few seconds and will then be returned by another
call.

Example responses

{
"pvSystemId": "04d81b82-7861-4e36-8e7f-41036ce711a4",
"status": {
"isOnline": true,
"battMode": "1.0"
},
"data": {
"logDateTime": "2019-06-18T14:01:57Z",
"channels": [
{
"channelName": "PowerFeedIn",
"channelType": "Power",
"unit": "W",
"value": -496.01
},

API Reference– 94
 [Link] Query API manual

{
"channelName": "PowerLoad",
"channelType": "Power",
"unit": "W",
"value": -186.89
},
{
"channelName": "PowerBattCharge",
"channelType": "Power",
"unit": "W",
"value": 0
},
{
"channelName": "PowerPV",
"channelType": "Power",
"unit": "W",
"value": 1682.9
},
{
"channelName": "PowerOhmpilot",
"channelType": "Power",
"unit": "W",
"value": null
},
{
"channelName": "BattSOC",
"channelType": "Percent",
"unit": "%",
"value": 99
},
{
"channelName": "RateSelfSufficiency",
"channelType": "Percent",
"unit": "%",
"value": 100
},
{
"channelName": "RateSelfConsumption",
"channelType": "Percent",
"unit": "%",
"value": 64.58
},
"channelName": "PowerEVCTotal",
"channelType": "Power",
"unit": "W",
"value": -1000.0
}
]
}
}

API Reference– 95
 [Link] Query API manual

6.6.2 Flowdata: Realtime power flow data of a device

Use cases for web developers
• I want to show current power flow for a a specific device.

Methods

Method End point and objects Event name Description

GET /pvsystems/{pv-system-id}/ GetDeviceFlowData Gets the real-time power flow
devices/{device-id}/flowdata data of the requested PV
device of a PV system with the
given ID.
The data is returned as a JSON
object.

Filters and parameters

Filter Description
?timezone=<"local", "zulu"> Specifies time format in response object:
• zulu (default): returns time in UTC zulu time
• local: returns time in PV system's local UTC time
(local time + UTC offset)

Example calls

GET [Link]/pvsystems/20bb600e-019b-4e03-9df3-a0a900cda689/devices/
d2e61bf2-8dd7-4ba1-8733-d55d738c4679/flowdata
// gets current power flow information for the given device

Response objects

JSON object answer construction:

Type Objects
inverter • PowerOutput
sensor • Temp1, Temp2
• Insolation
• Velocity
• Digital1, Digital2, Digital3

API Reference– 96
 [Link] Query API manual

Type Objects
battery • BattSOC
• BattMode
• PowerBattCharge
• BattSOH
• BattEnergyChargedTotal
• BattEnergyDischargedTotal
• MaxChargePower
• MaxDischargePower
Smart Meter • PowerFeedIn
• PowerLoad
• Power
• PowerExt
• PowerPurchase
Ohmpilot • PowerOhmpilot
• OhmpilotTemp
• OhmpilotState
Wattpilot (EV Charger) • PowerTotal
• EVCMode

Sometimes NULL values are returned, but another call a few seconds later returns valid
data.
This is because [Link] implements an asynchronous architecture. For the powerflow
data [Link] has to request the channel data from the devices first. Depending on the
round-trip time it can happen that [Link] internally runs into a timeout while waiting for
the data to be reported from the devices. Hence, SWQAPI then will return no values.
However, the data arrives usually after a few seconds and will then be returned by another
call.

Example responses

Example for an inverter

{
"pvSystemId": "04d81b82-7861-4e46-8e7f-41036ce711a4",
"deviceId": "c883f93f-6661-425f-a2c5-0f381ff86c89",
"status": {
"isOnline": true,
"battMode": 1.0

API Reference– 97
 [Link] Query API manual

},
"data": {
"logDateTime": "2020-03-26T14:34:20Z",
"channels": [
{
"channelName": "PowerOutput",
"channelType": "Power",
"unit": "W",
"value": 1041.0
}
]
}
}

Example for a battery

{
"pvSystemId": "5845cdf8-ae05-4cf8-a111-f1dc5665cae3",
"deviceId": "0ae28f7f-6983-422d-9615-56f168419074",
"status": {
"isOnline": true,
"battMode": 1.0
},
"data": {
"logDateTime": "2023-09-05T05:24:49Z",
"channels": [
{
"channelName": "BattSOC",
"channelType": "Percentage",
"unit": "%",
"value": 32.0
},
{
"channelName": "BattMode",
"channelType": "",
"unit": "",
"value": "Normal"
},
{
"channelName": "BattSOH",
"channelType": "Percentage",
"unit": "%",
"value": null
},
{
"channelName": "PowerBattCharge",
"channelType": "Power",
"unit": "W",
"value": null
},

API Reference– 98
 [Link] Query API manual

{
"channelName": "BattEnergyChargedTotal",
"channelType": "Energy",
"unit": "kWh",
"value": null
},
{
"channelName": "BattEnergyDischargedTotal",
"channelType": "Energy",
"unit": "kWh",
"value": null
},
{
"channelName": "MaxChargePower",
"channelType": "Power",
"unit": "W",
"value": null
},
{
"channelName": "MaxDischargePower",
"channelType": "Power",
"unit": "W",
"value": null
}
]
}
}

API Reference– 99
 [Link] Query API manual

6.7 Weather data calls

This set provides weather and energy forecast information for PV systems.

Two calls can check the current and future weather. The following info graphic gives you an
example:

A third call allows you to predict energy production for the next two days. You could might want to
create some diagrams like the following ones (see the hatched areas):

API Reference– 100

 [Link] Query API manual

6.7.1 Limitations
Only [Link] Premium users can access weather forecast information. For "Basic" users the
weather forecast APIs will return no data (403 error code).

Premium users receive full weather information for one "pro" system. For all other systems they
receive "light" information ("pro" channels will return null).

6.7.2 Weather: Current weather for a PV system

Use cases for web developers
• I want to show the current temperature, wind speed, precipitation for a given PV system.
• I want to know the time of sunrise and sunset.
• I want to show weather forecast symbols in my app.

Restrictions
• This call only works for a [Link] Premium customer who is entitled to get weather
forecast information, not for a basic customer.
• The precipitation, cloud coverage and daylight time channels are not available for "light" PV
systems.

API Reference– 101

 [Link] Query API manual

Methods

End point and

Method Event name Description
objects
GET /pvsystems/{pv- GetSystemWeatherCurre Gets the current weather information
system-id}/ nt for a given PV system.
weather/current

Filters and parameters

Filter Description
?channel=<channel> One or more of the detail data channels, e.g.
temperature or velocity.
?timezone=<"local", "zulu"> Specifies time format in response object:
• zulu (default): returns time in UTC zulu time
• local: returns time in PV system's local UTC time
(local time + UTC offset)

Example calls

GET [Link]/pvsystems/20bb600e-019b-4e03-9df3-a0a900cda689/weather/
current
// gets current weather information for PV system

GET [Link]/pvsystems/20bb600e-019b-4e03-9df3-a0a900cda689/weather/
current?channel=daylight&time=local
// gets today's sunrise and sunset times in local UTC time

GET [Link]/pvsystems/20bb600e-019b-4e03-9df3-a0a900cda689/weather/
current?channel=temp,symbol
// gets current temperature and symbol information

Response objects

JSON object answer construction:

API Reference– 102

 [Link] Query API manual

Objects
• pvSystemId (String)
• data
• logDateTime (DateTime)
• channels (Array)
• channelName (String)
• channelType (String)
• unit (String)
• value (Number or Object)

Supported value channels:

Type Channels Remarks

PV system • Temp Daylight with sunrise and sunset times.
• WindSpeed Precipitation, CloudCover and Daylight
• Precipitation channels only for "pro" systems.
• CloudCover
• Daylight
• Symbol

Example responses

Example for a "light" PV system

{
"pvSystemId": "04d81b82-7861-4e36-8e7f-41036ce711a4",
"data": {
"logDateTime": "2020-03-17T08:30:00+01:00",
"channels": [
{
"channelName": "Temp",
"channelType": "Temperature",
"value": 9.05,
"unit": "°C"
},
{
"channelName": "WindSpeed",
"channelType": "Velocity",
"value": 1.665,
"unit": "m/s"
},
{
"channelName": "Precipitation",
"channelType": "Precipitation",
"value": null,

API Reference– 103

 [Link] Query API manual

"unit": "mm"
},
{
"channelName": "CloudCover",
"channelType": "Cloudcoverage",
"value": null,
"unit": "%"
},
{
"channelName": "Daylight",
"channelType": "Daylight",
"value": {
"sunrise": null,
"sunset": null
},
"unit": "Time"
},
{
"channelName": "Symbol",
"channelType": "Symbol",
"value": "mostly cloudy",
"unit": null
}
]
}
}

6.7.3 Weather: Weather forecast for a PV system

Use cases for web developers
• I want to show weather forecast information for the next few days for a given PV system.
• I want to show weather forecast symbols in my app.

Restrictions
• This call only works for a [Link] Premium customer who is entitled to get weather
forecast information, not for a basic customer.
• The precipitation and daylight time channels are not available for "light" PV systems.

Methods

End point and

Method Event name Description
objects
GET /pvsystems/{pv- GetSystemWeatherForec Gets weather forecast information for
system-id}/ ast up to next 9 days.
weather/forecast

API Reference– 104

 [Link] Query API manual

Filters and parameters

Filter Description
?channel=<channel> One or more of the detail data channels, e.g.
temperature or velocity.
?timezone=<"local", "zulu"> Specifies time format in response object:
• zulu (default): returns time in UTC zulu time.
• local: returns time in PV system's local UTC time
(local time + UTC offset).
?from=<start>&to=<end> Limits the time series for the query.
• <start> and <end> are days, local time of the PV
system.
• Alternatively, <start> can also be
"today" (default) or "tomorrow"; <end> can be
"tomorrow".
• Date format encoding: "yyyyMMdd", "yyyy-MM-dd".
?from=<start>&duration=<days> Limits the time series for the query.
• <start> is a day, local time of the PV system.
• Alternatively, <start> can also be
"today" (default) or "tomorrow".
• <duration> is the number of days.
• <duration>=1 means only one single day.
• If <duration> is missing, the maximum period
is assumed, i.e. full 9 days of weather forecast.
• Date format encoding: "yyyyMMdd", "yyyy-MM-dd".

Example calls

GET [Link]/pvsystems/20bb600e-019b-4e03-9df3-a0a900cda689/weather/
forecast
// gets weather forecast for PV system for the next nine days, starting today

GET [Link]/pvsystems/20bb600e-019b-4e03-9df3-a0a900cda689/weather/
forecast?start=tomorrow&duration=7
// gets weather forecast for PV system for the next week, starting with tomorrow

GET [Link]/pvsystems/20bb600e-019b-4e03-9df3-a0a900cda689/weather/
forecast?channel=temp,daylight&time=local
// gets weather forecast for PV system for the next nine days, starting today
// the daylight times are returned in local UTC time

API Reference– 105

 [Link] Query API manual

Response objects

JSON object answer construction:

Type Objects
• pvSystemId (String)
• data
• logDateTime (Date)
• channels (Array)
• channelName (String)
• channelType (String)
• unit (String)
• value (Number or Object)

Supported value channels:

Type Channels Remarks

PV system • Temp Temperatures with temperatureMin and
• Daylight temperatureMax values.
• Symbol Daylight with sunrise and sunset times.
• EnergyExpected Precipitation and Daylight channels only for
"pro" systems.

Example responses

{
"pvSystemId": "04d81b82-7861-4e36-8e7f-41036ce711a4",
"data": [
{
"logDateTime": "2020-03-18T23:00:00Z",
"channels": [
{
"channelName": "Temp",
"channelType": "Temperature",
"value": {
"temperatureMin": 5.05,
"temperatureMax": 16.85
},
"unit": "°C"
},
{
"channelName": "Daylight",
"channelType": "Daylight",
"value": {
"sunrise": null,
"sunset": null
},

API Reference– 106

 [Link] Query API manual

"unit": "Time"
},
{
"channelName": "Symbol",
"channelType": "Symbol",
"value": "bright",
"unit": null
},
{
"channelName": "EnergyExpected",
"channelType": "Energy",
"value": null,
"unit": "Wh"
}
]
}
]
}

6.7.4 Weather: Energy forecast for a PV system

Use cases for web developers
• I want to extend an energy production curve (historical information) with forecast
information (future prediction).

Restrictions
• This call only works for a [Link] Premium customer who is entitled to get weather
forecast information, not for a basic customer.
• This call only works for a pro PV system.
• Data granularity:
• next 24 hours: 15min resolution
• following 24 hours: 1h resolution

Methods

End point and

Method Event name Description
objects
GET /pvsystems/{pv- GetSystemWeatherEnerg Gets energy production forecast
system-id}/ yforecast information for up to next 2 days.
weather/
energyforecast

Filters and parameters

API Reference– 107

 [Link] Query API manual

Filter Description
?timezone=<"local", "zulu"> Specifies time format in response object:
• zulu (default): returns time in UTC zulu time.
• local: returns time in PV system's local UTC time
(local time + UTC offset).
?from=<start>&to=<end> Limits the time series for the query.
• <start> and <end> are ISO-8601 time values.
• Time format encoding: "yyyyMMddTHHmmssTZD",
"yyyy-MM-ddTHH:mm:ssTZD".
?from=<start>&duration=<hours> Limits the time series for the query.
• <start> is an ISO-8601 time value.
• <duration> a number of 1 to 48 hours.
• If <duration> is missing, the maximum period
is assumed, i.e. full two days of energy
forecast.
• Time format encoding: "yyyyMMddTHHmmssTZD",
"yyyy-MM-ddTHH:mm:ssTZD".

Example calls

GET [Link]/pvsystems/20bb600e-019b-4e03-9df3-a0a900cda689/weather/
energyforecast
// gets energyforecast information for PV system for the next 48 hours

GET [Link]/pvsystems/20bb600e-019b-4e03-9df3-a0a900cda689/weather/
energyforecast?duration=8
// gets energyforecast information for PV system for the next 8 hours

Response objects

JSON object answer construction:

Type Objects
• pvSystemId (String)
• data (Array)
• logDateTime (DateTime)
• logDuration (Integer - unit: seconds)
• channels (Array)
• ChannelName (String)
• ChannelType (String)
• Unit (String)
• Value (Number)

API Reference– 108

 [Link] Query API manual

Supported value channels:

Type Channels Remarks

PV system • EnergyExpected

Example responses

{
"pvSystemId": "5b72b205-b698-4243-a68a-a39200e0e9d8",
"data": [
{
"logDateTime": "2020-01-07T12:30:00Z",
"logDuration": 900,
"channels": [
{
"channelName": "EnergyExpected",
"channelType": "Energy",
"value": 24.43275,
"unit": "Wh"
}
]
},
{
"logDateTime": "2020-01-07T12:45:00Z",
"logDuration": 900,
"channels": [
{
"channelName": "EnergyExpected",
"channelType": "Energy",
"value": 26.23989,
"unit": "Wh"
}
]
}
]
}

API Reference– 109

 [Link] Query API manual

6.8 System messages calls

6.8.1 Messages: Get PV system messages

Use cases for web developers
• I want to show system and error messages to the user.

Methods

End point and

Method Event name Description
objects
GET /pvsystems/{pv- GetSystemMessages Returns service messages for a given
system-id}/ PV system in English (default
messages language). The service messages are
provided as JSON objects.
GET /pvsystems/{pv- GetSystemMessages Returns service messages for a given
system-id}/ PV system in a certain language. The
messages/{ISO- service messages are provided as
country-code} JSON objects in the language defined
by the <ISO-country-code> object.

Note: Since the difference is only the language, the event is the same and the language is encoded
in the event log.

Filters and parameters

Filter Description
?timezone=<"local", "zulu"> Specifies time format in response object:
• zulu (default): returns time in UTC zulu time
• local: returns time in PV system's local UTC time
(local time + UTC offset)
?offset=<offset>&limit=<limit> Supports pagination, returns messages from a starting
<offset> and returning not more than <limit> items.

API Reference– 110

 [Link] Query API manual

Filter Description
?from=<start>&to=<end> Limits the time series for the query.
• <start> and <end> are ISO-8601 time values.
• If "to" is missing, then "to" is considered "now".
("from" must not be empty.)
• Time format encoding:
"yyyyMMddTHHmmssTZD", "yyyy-MM-
ddTHH:mm:ssTZD".
?statetype=<type> Filters by StateType, e.g. "Error", "Event".
?stateseverity=<level> Filters by StateSeverity, i.e. "Error", "Warning",
"Information".
?statecode=<code> Filters by StateCode.
?type=<devicetype> Type filter - one or more (comma separated, no spaces)
types of devices whose messages should be shown:
• inverter
• sensor
• battery
• smartmeter
• ohmpilot
• datalogger
• evcharger

Example calls

GET [Link]/pvsystems/20bb600e-019b-4e03-9df3-a0a900cda689/messages?
from=2018-10-10T00:00:00Z&to=2018-10-11T00:00:00Z
// gets all system messages for 10th of October, 2018, for PV system

Response objects

JSON object answer construction:

API Reference– 111

 [Link] Query API manual

Type Objects
PV systems • pvSystemId (String)
• deviceId (String)
• stateType (String)
• stateSeverity (String)
• stateCode (Integer)
• logDateTime (String, UTC timestamp)
• text (String) - language depends on <ISO-country-code>
object

Example responses

[
{
"pvSystemId": "d587d328-3cac-4953-9caf-a4bb009def43",
"deviceId": "b6f5495d-e0e7-49c2-80d6-e0bcd0ebacdc",
"stateType": "Error",
"stateSeverity": "Error",
"stateCode": 509,
"logDateTime": "2019-01-08T09:32:00Z",
"text": "No Feed In For 24 Hours"
},
{
"pvSystemId": "d587d328-3cac-4953-9caf-a4bb009def43",
"deviceId": "b6f5495d-e0e7-49c2-80d6-e0bcd0ebacdc",
"stateType": "Error",
"stateSeverity": "Error",
"stateCode": 901,
"logDateTime": "2018-12-27T23:50:00Z",
"text": "Current Sensor Deviation On Channel 1"
},
{
"pvSystemId": "d587d328-3cac-4953-9caf-a4bb009def43",
"deviceId": null,
"stateType": "Error",
"stateSeverity": "Error",
"stateCode": 906,
"logDateTime": "2018-12-26T12:38:07Z",
"text": "Heating rod 1 defective - short circuit L1"
},
{
"pvSystemId": "d587d328-3cac-4953-9caf-a4bb009def43",
"deviceId": "b6f5495d-e0e7-49c2-80d6-e0bcd0ebacdc",
"stateType": "Error",
"stateSeverity": "Error",
"stateCode": 475,
"logDateTime": "2018-12-24T09:03:00Z",
"text": "Isolation Error"

API Reference– 112

 [Link] Query API manual

},
{
"pvSystemId": "d587d328-3cac-4953-9caf-a4bb009def43",
"deviceId": "b6f5495d-e0e7-49c2-80d6-e0bcd0ebacdc",
"stateType": "Error",
"stateSeverity": "Error",
"stateCode": 901,
"logDateTime": "2018-12-27T23:50:00Z",
"text": "Current Sensor Deviation On Channel 1"
}
]

6.8.2 Messages: Count PV system messages

Use cases for web developers
• I want to know how many error messages I have to show. (Needed for subsequent
enumeration and detail calls.)

Methods

End point and

Method Event name Description
objects
GET /pvsystems/{pv- GetSystemMessagesCoun Returns number of service messages
system-id}/ t for a given PV system.
messages-count

Filters and parameters

Filter Description
?from=<start>&to=<end> Limits the time series for the query.
• <start> and <end> are ISO-8601 time values.
• If "to" is missing, then "to" is considered "now".
("from" must not be empty.)
• Time format encoding:
"yyyyMMddTHHmmssTZD", "yyyy-MM-
ddTHH:mm:ssTZD".
?statetype=<type> Filters by StateType, e.g. "Error", "Event".
?stateseverity=<level> Filters by StateSeverity, i.e. "Error", "Warning",
"Information".
?statecode=<code> Filters by StateCode.

API Reference– 113

 [Link] Query API manual

Filter Description
?type=<devicetype> Type filter - one or more (comma separated, no spaces)
types of devices whose messages should be shown:
• inverter
• sensor
• battery
• smartmeter
• ohmpilot
• datalogger
• evcharger

Example calls

GET [Link]/pvsystems/20bb600e-019b-4e03-9df3-a0a900cda689/messages-
count?from=2018-10-10T00:00:00Z&to=2018-10-11T00:00:00Z
// counts all system messages for 10th of October, 2018, for PV system

Response objects

JSON object answer construction:

Type Objects
n/a • count (Number)

Example responses

{
"count": 5
}

6.8.3 Messages: Get device system messages

Use cases for web developers
• I want to show system and error messages to the user.

Methods

API Reference– 114

 [Link] Query API manual

End point and

Method Event name Description
objects
GET /pvsystems/{pv- GetDeviceMessages Returns service messages for the
system-id}/ requested device of a PV system with
devices/{device-id the given ID in English (default
}/messages language). The service messages are
provided as JSON objects.
GET /pvsystems/{pv- GetDeviceMessages Returns service messages for the
system-id}/ requested device of a PV system with
devices/{device-id the given ID in a certain language. The
}/messages/{ISO- service messages are provided as
country-code} JSON objects in the language defined
by the <ISO-country-code> object.

Note: Since the difference is only the language, the event is the same and the language is encoded
in the event log.

Filters and parameters

Filter Description
?timezone=<"local", "zulu"> Specifies time format in response object:
• zulu (default): returns time in UTC zulu time
• local: returns time in PV system's local UTC time
(local time + UTC offset)
?offset=<offset>&limit=<limit> Supports pagination, returns messages from a starting
<offset> and returning not more than <limit> items.
?from=<start>&to=<end> Limits the time series for the query.
• <start> and <end> are ISO-8601 time values.
• If "to" is missing, then "to" is considered "now".
("from" must not be empty.)
• Time format encoding:
"yyyyMMddTHHmmssTZD", "yyyy-MM-
ddTHH:mm:ssTZD".
?statetype=<type> Filters by StateType, e.g. "Error", "Event".
?stateseverity=<level> Filters by StateSeverity, i.e. "Error", "Warning",
"Information".
?statecode=<code> Filters by StateCode.

Example calls

API Reference– 115

 [Link] Query API manual

GET [Link]/pvsystems/20bb600e-019b-4e03-9df3-a0a900cda689/devices/
d2e61bf2-8dd7-4ba1-8733-d55d738c4679/messages?from=2018-10-10T00:00:00Z&to=2018-10-11
T00:00:00Z
// gets all system messages for device for 10th of October, 2018

Response objects

JSON object answer construction:

Type Objects
Device • pvSystemId (String)
• deviceId (String)
• stateType (String)
• stateSeverity (String)
• stateCode (Integer)
• logDateTime (String, UTC timestamp)
• text (String) - language depends on <ISO-country-code> object

Example responses

[
{
"pvSystemId": "d587d328-3cac-4953-9caf-a4bb009def43",
"deviceId": "d2e61bf2-8dd7-4ba1-8733-d55d738c4679",
"stateType": "Error",
"stateSeverity": "Error",
"stateCode": 509,
"logDateTime": "2019-01-08T09:32:00Z",
"text": "No Feed In For 24 Hours"
},
{
"pvSystemId": "d587d328-3cac-4953-9caf-a4bb009def43",
"deviceId": "d2e61bf2-8dd7-4ba1-8733-d55d738c4679",
"stateType": "Error",
"stateSeverity": "Error",
"stateCode": 901,
"logDateTime": "2018-12-27T23:50:00Z",
"text": "Current Sensor Deviation On Channel 1"
}
]

6.8.4 Messages: Count device system messages

Use cases for web developers

API Reference– 116

 [Link] Query API manual

• I want to know how many error messages I have to show. (Needed for subsequent
enumeration and detail calls.)

Methods

End point and

Method Event name Description
objects
GET /pvsystems/{pv- GetDeviceMessagesCount Returns number of service messages
system-id}/ for the requested device of a PV
devices/{device- system with the given ID.
id}/messages-
count

Filters and parameters

Filter Description
?from=<start>&to=<end> Limits the time series for the query.
• <start> and <end> are ISO-8601 time values.
• If "to" is missing, then "to" is considered "now".
("from" must not be empty.)
• Time format encoding:
"yyyyMMddTHHmmssTZD", "yyyy-MM-
ddTHH:mm:ssTZD".
?statetype=<type> Filters by StateType, e.g. "Error", "Event".
?stateseverity=<level> Filters by StateSeverity, i.e. "Error", "Warning",
"Information".
?statecode=<code> Filters by StateCode.

Example calls

GET [Link]/pvsystems/20bb600e-019b-4e03-9df3-a0a900cda689/devices/
d2e61bf2-8dd7-4ba1-8733-d55d738c4679/messages-count?from=2018-10-10T00:00:00Z&to=2018-1
0-11T00:00:00Z
// counts all system messages for device for 10th of October, 2018

Response objects

JSON object answer construction:

API Reference– 117

 [Link] Query API manual

Type Objects
n/a • count (Number)

Example responses

{
"count": 2
}

7 Appendix

7.1 Response and error codes

7.1.1 HTML error codes

Used HTML response codes by SWQAPI:

Code Short description Description

200 OK Successful
201 Created Request was successful and a new resource has
been created
204 No content Successful request, no data returned
400 Bad request Malformed request
401 Unauthorized No or invalid authentication details are provided
403 Forbidden Authentication succeeded but authenticated
user/API key doesn't have access to the
resource
404 Not found Non-existent resource is requested
405 Method not allowed The request method is not supported for the
requested resource
409 Conflict The request could not be processed because of
a state-conflict
415 Unsupported media type Payload format is not supported
422 Unprocessable content The server cannot process the content
429 Too many requests Request is rejected due to rate limiting
500 Internal server error An unexpected server error happened

Appendix– 118
 [Link] Query API manual

Code Short description Description

503 Service not available The server is temporarily unavailable

7.1.2 Detailed error codes

If an error happens, Fronius APIs indicate the error reason in the JSON response object.

Error code examples

{
"responseError": 1008,
"responseMessage": "Invalid channels:
EnergyBatteryDischarge,EnergyBatteryDischarge"
}

{
"responseError": 1005,
"responseMessage": "Invalid date and time format."
}

{
"responseError": 1004,
"responseMessage": "Input invalid. Unrecognized parameters: cannel"
}

List of detailed error codes

Fronius
Verbose Description Comment
Response Code
GENERAL (10xx)
1001 Error while processing General error for internal server.
request.
1002 Requested resource not
found.
1003 No input set.
1004 Input invalid. The reason for the error is usually given.

Appendix– 119
 [Link] Query API manual

Fronius
Verbose Description Comment
Response Code
1005 Invalid date and time format.
1006 Invalid date format.
1007 Invalid timezone parameter.
1008 Invalid channels List of invalid channels is appended at the end.
1009 Invalid language code
1010 From date is after to date.
1011 API calls quota exceeded. "Maximum admitted {0} per {1}. Retry after: {2}"
added to message.
1012 The API is not available due to Maintenance end time is added to the message.
server maintenance. The
maintenance window lasts
until {0}.
1013 User not authorized for PV
system.
1015 PV system not found.
1016 Error while processing
request.
AUTHENTICATION (11xx)
1101 AccessKeyId and Value not
sent.
1102 AccessKey not found.
1103 AccessKey is not active.
1104 AccessKey expired.
1105 User blocked.
1106 Authentication failed.
1107 Invalid request. JWT generation failed, usually because of
invalid data.
1108 User did not accept latest
Terms of Use.
1110 Invalid JWT format.
1111 Invalid JWT signature.
1112 Invalid JWT issuer.
1113 JWT expired.

Appendix– 120
 [Link] Query API manual

Fronius
Verbose Description Comment
Response Code
1114 Missing parameters: UserId, Missing parameters could be UserId or
Password Password
1115 Empty parameters: UserId, Empty parameters could be UserId or Password
Password
1116 Invalid scope. Token likely
expired.
1118 Invalid JWT.
1120 Refresh token invalid.
1121 Refresh token expired.
1122 Account temporarily blocked -
too many login attempts.
1123 There was no [Link] user
found, User needs to log in to
[Link] Portal once.
Metadata calls (30xx)
3001 Type filters invalid. List of invalid type filters is appended at the
end.
3002 Invalid meteo parameter. Wrong meteo filter. Only "pro" or "light" values
are valid.
3003 Error fetching Data from An unexpected error happened while retrieving
Database. data from database.
Power flow data (flowdata) calls (31xx)
31xx
Aggregation data (aggdata, aggrdata) calls (32xx)
3201 Invalid date format for "from"
parameter.
3202 Invalid date format for "to"
parameter.
3203 Invalid duration format.
3204 Invalid combination of Only from and to, or from and duration are
parameters. allowed.
3205 Invalid duration range. Maximum range is 100 years.
3206 From and to parameters do
not have same format.

Appendix– 121
 [Link] Query API manual

Fronius
Verbose Description Comment
Response Code
3207 Period parameter should not Do not use from, to or duration, in combination
be used in combination with with period parameter.
other time parameters.
Historical data (histdata) calls (33xx)
3301 Date range max is 24 hours. The maximum time range that can be queried is
24 hours - mainly because calls would take too
long otherwise.
If you need data for more than a day, please
split the query into multiple calls with no more
than 24 hours each.
3302 User unauthorized to access Impersonated basic users can only retrieve
requested time range. information not older than 72 hours - like in
[Link].
Messages calls (34xx)
3401 Invalid state type.
3402 Invalid state code.
3403 Date range between from and
to filters too big.
3404 From date is required.
3405 Invalid state severity.
Weather calls (35xx)
3501 Invalid parameter
combination.
3502 No POI data for PV system. PV system does not have POI information
assigned.
3503 Not a Pro PV system. Pro user is requesting energy forecast
information for a "light" PV system. (Forecast
information is only available for "pro" systems.)
Info calls (36xx)
3601 TermsAcceptedLatest cannot
be set to false.

Appendix– 122
 [Link] Query API manual

7.2 Response Headers

The API returns HTTP response headers to clients which can provide more detail context.

Name Description Example

Cache-Control Indicates that the response can be max-age=3600
cached for N seconds before getting
refreshed
X-Rate-Limit-Limit Request limit per period; the limit 1h
defines the time window length
X-Rate-Limit-Remaining Number of requests left for the time 21942
window
X-Rate-Limit-Reset The time when the rate limit resets (in 2024-03-28T13:00:00.00000
UTC) 00Z

7.2.1 Rate limit headers

To avoid DOS attacks or overloading, the API implements rate limiting. Rate limit is implemented
very flexible; there are rate limits applied per hour, per minute, and per second.

Typical rate limits are e.g. 30,000 calls per hour, 1,000 calls per minute and 100 calls per
second.
If you need different rate limits for your application, please contact Fronius.

Whenever a rate limit is hit, the API will return a 429 error (together with a verbose error response
description).

Interpreting the rate limit response headers allows callers to find out how many calls are still
possible. If the rate limit already applied, it is possible to find out when the next call can be done.

Example (1h rate limit is typically 30,000 calls):

7.2.2 Cache control headers (max-age)

Cache-Control headers are added to the responses of the following endpoints upon successful
requests. If a request is unsuccessful, no Cache-Control header will be added.

Appendix– 123
 [Link] Query API manual

Historical Data
• GET /pvsystems/{pv-system-id}/histdata
• GET /pvsystems/{pv-system-id}/devices/{device-id}/histdata
Historical data is expected to be received once per hour. Allowing a two-minute tolerance, the
maxAge for these endpoints can be set to up to 3720 seconds. If historical data for multiple
devices is requested, maxAge is calculated based on the oldest import. If the last import is
overdue, meaning it is older than the expected hourly interval, maxAge will be reduced to 120
seconds to enable more frequent updates. If the last import time for the requested device(s)
cannot be verified, maxAge will be set to 600 seconds (10 minutes).

Weather forecast (energy forecast)

• GET /pvsystems/{pv-system-id}/weather/current
• GET /pvsystems/{pv-system-id}/weather/forecast
• GET /pvsystems/{pv-system-id}/weather/energyforecast

For calculating maxAge , different intervals are considered based on the type of PV system:

▪ "Pro" Pv Systems ([Link] Premium "Pro" PP System)

Weather updates occur every two hours, allowing for a maxAge of up to 7320 seconds with
a two-minute tolerance.
Power forecast updates occur every hour, with a maxAge of up to 3720 seconds, including
tolerance.
maxAge will be calculated until the next weather or power update is expected. If the last
update is overdue, maxAge will be set to 120 seconds to enable frequent updates.
▪ "Light" Pv Systems ([Link] Premium "Light PV System)
Weather updates occur every four hours, allowing for a maxAge of up to 14640 seconds,
including tolerance.
maxAge will be calculated until the next weather update is expected. If the last update is
overdue, maxAge will be set to 120 seconds.
▪ "Basic" Pv Systems with a weather POI
Weather updates occur every four hours. maxAge will be calculated until the next weather
update is expected. If the last update is overdue, maxAge will be set to 120 seconds.
▪ "Basic" Pv Systems without a weather POI
MaxAge will be 14640 seconds.

Example Response Headers

Appendix– 124
 [Link] Query API manual

Appendix– 125
 [Link] Query API manual

7.3 Channels

7.3.1 Channel list

Appendix– 126
 [Link] Query API manual

aggda
Channel name in flowd ta, histda weath
Channel Device type Unit Description
[Link] UI ata aggrd ta er
ata
ApparentPower Apparent power inverter VA Apparent power (S) x
BattEnergyCharge battery kWh Total lifetime battery charge x
dTotal
BattEnergyDischa battery kWh Total lifetime battery discharge x
rgedTotal
BattMode battery Battery operating state. State values are: x x
• 0 = Disabled
• 1 = Normal
• 2 = ServiceMode
• 3 = ChargeBoost
• 4 = NearlyDepleted
• 5 = SuspendedOnPurpose
• 6 = Calibrate
• 7 = GridSupport
• 8 = DepletedRecovery
• 9 = NonOperableTemperature
• 10 = NonOperableVoltage
• 11 = Preheating
• 12 = Startup
• 13 = AwakeButNonOperableTemperature
• 14 = BatteryFull
• 90 = ForcedStandby

Appendix – 127
 [Link] Query API manual

aggda
Channel name in flowd ta, histda weath
Channel Device type Unit Description
[Link] UI ata aggrd ta er
ata
BattSOC State of charge battery, % Battery state of charge x x
general
BattSOH battery % Battery state of health x
CloudCover % Cloud coverage x
CurrentA, Current AC L1, inverter, A Mean current of 3-phase devices on the AC side of x
CurrentB, Current AC L2, evcharger the device for line L1 / L2 / L3
CurrentC Current AC L3
CurrentDC1, Current DC MPP1, inverter A Mean current on the DC side of the inverter for x
CurrentDC2, Current DC MPP2 DC1 / DC2
...
Daylight (sunrise, time Sunrise and sunset times x
sunset)
Digital1, sensor <variable> Digital channel from Fronius Sensor Card (unit x
Digital2, depends on sensor settings)
Digital3
Digital1Energy, sensor Wh Energy measured by sensor. x
Digital2Energy, Note: DigitalX and DigitalXEnergy exclude each
Digital3Energy other.
Earnings Earning general <currency> Energy fed into grid multipled by a tariff. x

Appendix – 128
 [Link] Query API manual

aggda
Channel name in flowd ta, histda weath
Channel Device type Unit Description
[Link] UI ata aggrd ta er
ata
EnergyBattCharge Energy to battery general Wh Calculated energy flowing from generators to x x
batteries
EnergyBattCharge general Wh Calculated energy flowing from grid to battery x x
Grid
EnergyBattDischa Energy from general Wh Calculated energy flowing from batteries to x x
rge battery consumer
EnergyBattDischa general Wh Calculated energy flowing from battery to grid x x
rgeGrid
EnergyChargeTota evcharger Wh Total energy consumed by Wattpilot x
l
EnergyConsumpti Consumption general Wh Calculated consumed energy (EnergyPurchased + x x
onTotal EnergySelfConsumption + EnergyBattDischarge)
EnergyDC1, Power MPP1, inverter Wh Calculated energy flowing from generator into x x
EnergyDC2, Power MPP2 inverter on DC1 / DC2 input
...
EnergyDirectCons Consumed general Wh Calculated energy flowing from generators to x
umption directly consumers (excluding Ohmpilot + Wattpilot)
(Production tab)
EnergyEVCCharge general Wh Energy flowing from generators to Wattpilot x x

Appendix – 129
 [Link] Query API manual

aggda
Channel name in flowd ta, histda weath
Channel Device type Unit Description
[Link] UI ata aggrd ta er
ata
EnergyEVCCharge general Wh Energy flowing from battery to Wattpilot x x
Batt
EnergyEVCCharge general Wh Energy flowing from grid to Wattpilot x x
Grid
EnergyEVCCharge general Wh Total energy consumed by Wattpilot x
Total
EnergyExpected general Wh Energy forecast x
EnergyExported Total power general, Wh Total energy flowing out of the main inverter x x
Production (for inverter, (generators sum + battery)
smartmeter) smartmeter
EnergyFeedIn Power to grid general Wh Calculated energy flowing from generators to grid x x
EnergyImported Consumption inverter, Wh Total energy flowing into the main (hybrid) x
smartmeter inverter.
This energy comes either from the grid or from
another inverter, and usually it is stored in a
battery.
EnergyLoad smartmeter Wh Energy flowing into the consumers x
EnergyLoadAbs smartmeter Wh Energy flowing into the consumers (absolute x
value)

Appendix – 130
 [Link] Query API manual

aggda
Channel name in flowd ta, histda weath
Channel Device type Unit Description
[Link] UI ata aggrd ta er
ata
EnergyOutput general Wh Calculated total energy produced (NULL if smart x x
meter is connected)
EnergyProduction Production general Wh Calculated energy flowing from generators to x x
Total consumer, battery and grid
(EnergySelfConsumption + EnergyBattCharge +
EnergyFeedIn + EnergyOutput)
EnergyPurchased Power from grid general Wh Calculated energy flowing from grid to consumer x x
EnergySelfConsu Consumed general Wh Calculated energy flowing from generators to x x
mption directly consumers (including Ohmpilot + Wattpilot)
(Consumption tab)
EnergySelfConsu Own consumption general Wh Calculated energy flowing from generators to x x
mptionTotal consumers and battery (EnergySelfConsumption
+ EnergyBattCharge)

Appendix – 131
 [Link] Query API manual

aggda
Channel name in flowd ta, histda weath
Channel Device type Unit Description
[Link] UI ata aggrd ta er
ata
EVCMode evcharger Active charging mode of Wattpilot (refer to x
Wattpilot documentation for details):
• EcoMode
• NextTripMode
• StandardMode
• NoCar
• NotCharging
• WaitingForPrice
• FullyCharged
• ConnectionLost
• PvConnectionLost
ExtEnergyExporte smartmeter Wh Energy flowing from external AC source (e.g. wind x
d power generator) to the point of common
coupling
ExtEnergyExporte smartmeter Wh Energy flowing from external AC source (e.g. wind x
dAbs power generator) to the point of common
coupling (absolute value)

Appendix – 132
 [Link] Query API manual

aggda
Channel name in flowd ta, histda weath
Channel Device type Unit Description
[Link] UI ata aggrd ta er
ata
GridApparentPow Apparent power smartmeter VA Mean apparent power of 3-phase devices of the x
erA, L1 feed-in-point, grid phase 1 / 2 / 3 measured by primary grid
GridApparentPow Apparent power meter in the given interval
erB, L2 feed-in-point,
GridApparentPow Apparent power
erC L3 feed-in-point
GridEnergyExport smartmeter Wh Energy flowing from the house into grid x
ed
GridEnergyExport smartmeter Wh Energy flowing from the house into grid (absolute x
edAbs value)
GridEnergyImport smartmeter Wh Energy imported from grid x
ed
GridEnergyImport smartmeter Wh Energy imported from grid (absolute value) x
edAbs
GridPowerA, Effective power L1 smartmeter W Mean power of 3-phase devices of the grid phase x
GridPowerB, feed-in point, 1 / 2 / 3 measured by primary grid meter in the
GridPowerC Effective power L2 given interval
feed-in point,
Effective power
L3 feed-in point

Appendix – 133
 [Link] Query API manual

aggda
Channel name in flowd ta, histda weath
Channel Device type Unit Description
[Link] UI ata aggrd ta er
ata
GridVoltageA, Voltage AC L1 smartmeter V Mean voltages of 3-phase devices of the grid x
GridVoltageB, feed-in point, phase 1 / 2 / 3 measured by primary load meter in
GridVoltageC Voltage AC L2 the given interval
feed-in point,
Voltage AC L3
feed-in point
Insolation Insolation sensor W/m2 Insolation x
IsOnline general - Online status of the PV system x
LoadApparentPow smartmeter VA Mean apparent power of 3-phase devices of the x
erA, load phase 1 / 2 / 3 measured by primary load
LoadApparentPow meter in the given interval
erB,
LoadApparentPow
erC
LoadPowerA, smartmeter W Mean power of 3-phase devices of the load phase x
LoadPowerB, 1 / 2 / 3 measured by primary load meter in the
LoadPowerC given interval
LoadVoltageA, smartmeter V Mean voltage of 3-phase devices of the load phase x
LoadVoltageB, 1 / 2 / 3 measured by primary load meter in the
LoadVoltageC given interval
MaxChargePower battery W Maximum power for battery charging x

Appendix – 134
 [Link] Query API manual

aggda
Channel name in flowd ta, histda weath
Channel Device type Unit Description
[Link] UI ata aggrd ta er
ata
MaxDischargePow battery W Maximum power for battery discharging x
er
OhmpilotEnergy Power Ohmpilot Wh Energy used by Ohmpilot x x
OhmpilotEnergyA Ohmpilot Wh Absolute energy used by Ohmpilot x
bs
OhmpilotError Ohmpilot - Ohmpilot error code x
OhmpilotTemp Temperature Ohmpilot °C Temperature measured on Ohmpilot device x x
Ohmpilot
Power general W Power measured by a submeter (requires a Smart x
Meter)
PowerBattCharge general, W Power flowing from inverter to the battery or from x
battery battery to inverter (requires a Smart Meter and a
battery)
PowerEVCTotal general W Total power consumed by Wattpilot x
PowerExt general W Power generated by external inverter (requires a x
Smart Meter)
PowerFactor Power factor inverter, - Power factor x
evcharger
PowerFeedIn general W Power flowing from inverter to the grid (requires a x
Smart Meter)

Appendix – 135
 [Link] Query API manual

aggda
Channel name in flowd ta, histda weath
Channel Device type Unit Description
[Link] UI ata aggrd ta er
ata
PowerLoad general W Power flowing from inverter to the consumer x
(requires a Smart Meter)
PowerOhmpilot general W Power flowing from inverter to an Ohmpilot x
(requires a Smart Meter and an Ohmpilot)
PowerOutput general W Power generated by inverter (NULL if Smart x
Meter is connected)
PowerPurchase general W Power flowing in from grid (requires a Smart x
Meter)
PowerPV general W Power flowing from generators to the inverter x
PowerTotal evcharger W Power consumed by Wattpilot x
Precipitation mm Precipitation x
Profits general <currency> Total financial benefit of the PV system (Earnings x
+ Savings).
RateSelfConsump general % Percentage of produced energy which is directly x
tion used (compared to energy fed into the grid)
RateSelfSufficienc general % Percentage of produced energy of all energy used x
y (includes energy from the grid)
ReactivePower Reactive power inverter VAr Reactive power (Q) x
Savings general <currency> Directly consumed energy multiplied by a tariff. x

Appendix – 136
 [Link] Query API manual

aggda
Channel name in flowd ta, histda weath
Channel Device type Unit Description
[Link] UI ata aggrd ta er
ata
SavingsCO2 CO2 savings general kg Equivalent of saved CO2 due to PV production. x

SavingsTravelCar CO2 savings general km Equivalent of saved average car travel distance x
due to PV production.
SavingsTravelPlan CO2 savings general mile Equivalent of saved average air travel distance due x
e to PV production.
SavingsTrees CO2 savings general tree Equivalent of saved average trees due to PV x
production.
StandardizedPowe Standardized inverter % Percentage of power generated in relation to peak x
r power power (i.e. kWh/kWp)
Symbol symbol Weather forecast symbol x
Temp °C Current temperature x
Temp (min, max) °C Temperature forecast x
Temp1, Module sensor °C Temperature x
Temp2 temperature
VoltageA, Voltage AC L1, inverter, V Mean voltage of 3-phase devices on the AC side of x
VoltageB, Voltage AC L2, evcharger the device for line L1 / L2 / L3
VoltageC Voltage AC L3
VoltageAB, inverter V Mean voltage of 3-phase devices on the AC side of x
VoltageBC, the main inverter (voltages are between lines
VoltageCA L1L2 / L2L3 / L3L1)

Appendix – 137
 [Link] Query API manual

aggda
Channel name in flowd ta, histda weath
Channel Device type Unit Description
[Link] UI ata aggrd ta er
ata
VoltageDC1, Voltage DC MPP1, inverter V Mean voltage on the DC side of the inverter for x
VoltageDC2, Voltage DC MPP2 DC1 / DC2
...
WindSpeed sensor m/s Wind speed x x

Appendix – 138
 [Link] Query API manual

7.3.2 Channel types

Type Unit
Apparent Power VA
Boolean true or fals
CO2 savings kg, tree, km or mile
Currency <currency>
Current A
Energy Wh
Insolation W/m2
Percentage %
Power W
Precipitation (rain) mm
Reactive Power VAr
Symbol Symbol
Temperature °C
Time Time
Velocity (wind speed) m/s
Voltage V

Appendix– 139
 [Link] Query API manual

7.4 Meteorological weather symbols

7.4.1 List of weather symbols

Icon
Symbol description
(example)
clear sky

bright

cloudy

mostly cloudy

overcast

fog

low clouds

light rain

rain

heavy rain

drizzle

light freezing rain

heavy freezing rain

sunny with scattered rain showers

cloudy with scattered rain showers

overcast with scattered rain showers

sunny with heavy rain showers

cloudy with heavy rain showers

overcast with heavy rain showers

sunny with thunderstorms

cloudy with thunderstorms

Appendix– 140
 [Link] Query API manual

Icon
Symbol description
(example)
overcast with thunderstorms

sunny with strong thunderstorms

cloudy with strong thunderstorms

overcast with strong thunderstorms

light snowfall

snowfall

heavy snow

sunny with light snow showers

cloudy with light snow showers

overcast with light snow showers

sunny with heavy snow showers

cloudy with heavy snow showers

overcast with heavy snow showers

light sleet

sleet

heavy sleet

sunny with light sleet showers

cloudy with light sleet showers

overcast with light sleet showers

sunny with heavy sleet showers

cloudy with heavy sleet showers

sunny with heavy sleet showers

cloudy with heavy sleet showers

overcast with heavy sleet showers

Appendix– 141
 [Link] Query API manual

Icon
Symbol description
(example)
duststorm / sandstorm

drifting snow

graupel

fog patches

low clouds, sun

freezing fog

sun and high clouds

Appendix– 142
 [Link] Query API manual

7.5 Languages
SWQAPI supports the following languages in system messages and Terms of Use (ISO 639-1
language codes):

ISO Code Language ISO Code Language ISO Code Language

CS Czech FI Finnish PT Portuguese
DA Danish FR French RU Russian
DE German HU Hungarian SK Slovakian
EL Greek IT Italian SV Swedish
EN English NL Dutch TR Turkish
ES Spanish PL Polish

Appendix– 143
 [Link] Query API manual

7.6 Best practices and how-tos

7.6.1 Use filters for channels

It is highly recommended to use filters whenever possible even though all available channels are
requested. Fronius may add channels in the future so filters help to get the same number of
channels (and data points) without the need of changing any code.

7.6.2 Determine power values from energy values from historical data

Power [W] = Energy [Wh] * 3600 / logDuration [s]

logDuration (typ. 300 seconds) can be found in the response to /histdata endpoint:

{
"pvSystemId": "a69f2adc-5fd0-4321-8323-a484013871f6",
"deviceId": null,
"data": [
{
"logDateTime": "2021-01-19T09:00:00+01:00",
"logDuration": 300,
"channels": [
{
"channelName": "EnergyProductionTotal",
"channelType": "Energy",
"unit": "Wh",
"value": 34.99
},
...

7.6.3 Determine PV Energy and Load Energy

PV Energy = EnergySelfConsumption + EnergyFeedIn + EnergyBattCharge

Load Energy = EnergySelfConsumption + EnergyPurchased + EnergyBattDischarged

Appendix– 144
 [Link] Query API manual

7.6.4 Determine if new systems were added to account

Method 1 - only systems are added:

1. Simply request the system count (/pvsystems-count) for your account once in a while (e.g.
once per day).
2. Compare the value with the last one you received. If the new one is higher then there is a new
system.
3. Use the /pvsystems-list endpoint to get the PV system IDs.
4. Compare the IDs with your current list of IDs in order to find the ID of the new system.
5. Update your list of IDs.

Method 2 - if there are systems that are temporarily added to your account:

1. Use the /pvsystems-list endpoint to get the PV system IDs.

2. Compare the IDs with your current list of IDs in order to find the ID of the new system.
3. Update your list of IDs.
4. Use the /pvsystems-list endpoint repeatedly to determine if a PV system is removed from
account.
5. If an ID does not show up in the response anymore it can be deleted from your list.

7.6.5 Grant permissions in [Link]

When using the regular authentication method your user needs permission to access a PV system's
data through the API if you don't own it. Here's a short guide on how to grant permission.

The API user has to take care of getting the permission from the owner (or a supervisor) of
a PV system. Fronius does not grant anybody permission to a PV system that is not linked
to the account (by ownership or permission).

1. Log in to [Link] and select PV the system

2. Go to SETTINGS

Appendix– 145
 [Link] Query API manual

3. Go to PERMISSIONS (1) and click on ADD (2)

4. Enter the E-mail address of the account that shall get access to the system. Select a
permission level:
• Guest: in [Link] read only and no change of settings possible; service messages
cannot be read via SWQAPI.
• Supervisor: in [Link] change of settings possible; service messages can be read via
SWQAPI.
Click OK

Appendix– 146