fzj-iek3-vsa / ethos-builda-client

Repository for the Python client for ETHOS.BUILDA

!!! The API this client is accessing will be available from July 1st !!!

ETHOS.BUILDA-Client

Python client for the building database ETHOS.BUILDA.

This is a Python HTTP-client that provides methods for accessing the API endpoints of ETHOS.BUILDA. The endpoints are documented using Swagger and can be accessed here: https://ethos-builda.fz-juelich.de.

ETHOS.BUILDA is a database containing building-level data for the German building stock. It is based on various data sources that are combined and enriched with machine learning approaches to generate one consistent and complete building dataset. The database is released under the Open Data Commons Open Database License (ODbL).The license of the contents of the database are provided with the query results for the individual data points. Additionally, the sources of the data points and information on the type of processing that was done to assign the information from the raw data to the building in ETHOS.BUILDA are included in the query results.

Installation

You can install a specific release directly from remote repository via:

pip install git+https://github.com/FZJ-IEK3-VSA/[email protected]

If you execute this command without specifying the tag/release, you will install the latest release.

You can also install by downloading the repo to a local folder, checking out the tag/branch you need, cd-ing into it and installing the client into an environment of your choice (e.g. conda) via:

pip install .

For development, install in editable mode with:

pip install -e .

And if you want to execute tests:

pip install -e .[testing]

Or for development and testing:

pip install -e ".[test,development]"

Usage

Import and instantiate the client via:

from builda_client.client import BuildaClient
client = BuildaClient()

This is sufficient for the standard use case.

If you are an internal user at the IEK-3 of Forschungszentrum Jülich, please use the internal version of the client. Using this client, you have access to additional methods for querying and writing data. However, this requires a username and password as the respective API endpoints are not openly available (yet).

from builda_client.dev_client import BuildaDevClient
client = BuildaDevClient(username='your_username', password='your_password')

In both cases you then have access to methods for querying individual building and statistical data. Please be aware that querying large amounts of data can take a long time, so make use of the filter parameters to appropriately restrict your query.

building_data = client.get_residential_buildings(city='Jülich', street='Grünstr.')

You can access the buildings and convert them to a pandas dataframe by calling:

import pandas as pd
building_df = pd.DataFrame(building_data.buildings)

The values of the attributes are saved in the JSON dictionary with the key 'value'. Details for the source and lineage abbreviations used in the building data can be access via:

lineages = pd.DataFrame(building_data.lineages)
sources = pd.DataFrame(building_data.sources)

How to create new version

1. Set the base_url in config.yml to the new version of the API.
2. Test if the client still works by running the tests
3. Merge changes into main branch
4. Tag with version (e.g. v1.0)
5. Change base_url back to /api/v0 for further development

If you need to do changes to a version later, check out a new branch at the tag.

Create documentation in HTML and LaTeX format via tox -e docs_html,docs_latex

About us

We are the Institute of Energy and Climate Research - Jülich Systems Analysis (IEK-3) belonging to the Forschungszentrum Jülich. Our interdisciplinary institute's research is focusing on energy-related process and systems analyses. Data searches and system simulations are used to determine energy and mass balances, as well as to evaluate performance, emissions and costs of energy systems. The results are used for performing comparative assessment studies between the various systems. Our current priorities include the development of energy strategies, in accordance with the German Federal Government’s greenhouse gas reduction targets, by designing new infrastructures for sustainable and secure energy supply chains and by conducting cost analysis studies for integrating new technologies into future energy market frameworks.

Acknowledgements

This work was supported by the Helmholtz Association under the program "Energy System Design".

Note

This project has been set up using PyScaffold 4.2.3. For details and usage information on PyScaffold see https://pyscaffold.org/.