Using the TOP-Energy Server Version
The Python REST API has been tested with standard cases only, please use it carefully, and check every step.
For more information, see the Known Bugs article.
Calling the REST API
The REST API of TOP-Energy can be called both locally via http://localhost:8010 and remotely via the network via http://SERVER:8010. For external access via the network, the port 8010 may need to be enabled in the firewall.
Preparation and Installation of TOP-Energy
A special license is required to use the REST API. Please contact support to request one!
Then follow these steps:
- Install topenergy_setup_X.X.X.X-x64.msi with the setup type Complete.
- Alternatively, select the setup type Custom and then the installation of the REST API.
- Make sure that TOP-Energy is activated.
Installation of the Python Package
Call the REST API documentation: by the URL http://localhost:8010/api-doc or in the Windows Start Menu by TOP-EnergyX.X.X/TOP-Energy REST-API Documentation. Follow the installation instructions in this documentation.
Update of the TOP-Energy Version
When updating TOP-Energy to the latest version, you must update the Python package tepyapi using the following command (see also the REST API documentation).
pip install tepyapi ‐‐upgrade ‐‐index-url http://localhost:8010
Example
A minimal example of a Python script for using TOP-Energy via the Rest API is provided with the installation. You can find this TOP-Energy REST-API Example in the Windows Start Menu when you unfold TOP-Energy. Save this script and Tutorial 07 in the German version in a folder outside your user directory.
Notes on Use of the REST API via Python
First make sure, that the projects are executable in TOP-Energy. Potential errors (missing license, not connected pins, etc.) are not handled separately. Multi-criteria optimization and the Parameter study cannot be executed via the Rest API.
Path of the Folder with the TOP-Energy Project File
By default, the TOP-Energy Service is not authorized to access a user directory (e.g., C:\User\$User Name$) and cannot load the TOP-Energy file from there. To make this possible anyway, set the service to be executed as local machine administrator. From an IT security point of view, however, you should have good reasons for this, because it is like working with an admin account all the time. This risk is excluded by default.
Several TOP-Energy Versions
If there are several TOP-Energy versions with server installed, always the newest version is used. Two servers cannot run parallelly.
The services can be separately closed and started via the Windows services: by opening the commando line as administrator, opening services.msg and the service TOP-Energy Automation Service X.X.X (x64) afterwards.
If you want to use several versions alternatingly on one computer, in addition to manually starting/closing the services, make sure that the associated tepyapi package is used in Python. For example, different virtual environments can be used:
Creating a Virtual Environment for Version 3.4
Precondition: REST API-Service for TOP-Energy 3.4 is active.
python -m venv te_py_3_4
te_py_3_4\Scripts\activate # (Windows) | source te_py_3_4/bin/activate (Linux/macOS)
pip install tepyapi ‐‐index-url http://localhost:8010
Creating a Virtual Environment for Version 3.5
Precondition: REST API-Service for TOP-Energy 3.5 is active.
python -m venv te_py_3_5
te_py_3_5\Scripts\activate # (Windows) | source te_py_3_5/bin/activate (Linux/macOS)
pip install tepyapi ‐‐index-url http://localhost:8010
Updating the Time Series
Time series that are written in TOP-Energy components via the API must be sorted chronologically. They must not contain double values. The time series are not examined automatically. Please make sure that the time series are correct.
Dialog Defaults in TOP-Energy
You do not have access to the TOP-Energy dialogs via the REST API. Therefore, all dialogs are automatically answered with the respective default response, for example:
