Skip to content

Basic functions

open_mastr.Mastr

Mastr is used to download the MaStR database and keep it up-to-date.

An SQL database is used to mirror the MaStR database. It is filled by downloading and parsing the MaStR via bulk download.

Example

from open_mastr import Mastr

db = Mastr()
db.download()
PARAMETER DESCRIPTION
engine

Defines the engine of the database where the MaStR is mirrored to. Default is 'sqlite'.

TYPE: (sqlite, Engine) DEFAULT: 'sqlite'

connect_to_translated_db 
Allows connection to an existing translated database. Default is 'False'.
Only for 'sqlite'-type engines.

DEFAULT: False

browse_available_downloads()

Browse available MaStR downloads from the website without starting the download.

This method fetches and displays all available download dates from the MaStR website, allowing users to see what historical data is available before deciding to download.

RETURNS DESCRIPTION
list of dict

List of available downloads with date, version, and type information.

Examples:

>>> from open_mastr import Mastr
>>> db = Mastr()
>>> available_downloads = db.browse_available_downloads()
>>> # User can then choose a date and download with:
>>> # db.download(select_date_interactively=True)

download(method='bulk', data=None, date=None, bulk_cleansing=True, keep_old_downloads=False, select_date_interactively=False, **kwargs)

Downloads the MaStR registry and writes it to a local database.

PARAMETER DESCRIPTION
method

Only "bulk" is a valid value. The download via the MaStR SOAP API has been removed. Defaults to 'bulk'.

TYPE: bulk DEFAULT: 'bulk'

data

Specifies which tables to download.

Possible values:

  • "wind"
  • "solar"
  • "biomass"
  • "hydro"
  • "gsgk"
  • "combustion"
  • "nuclear"
  • "gas"
  • "storage"
  • "storage_units"
  • "electricity_consumer"
  • "location"
  • "market"
  • "grid"
  • "balancing_area"
  • "permit"
  • "deleted_units"
  • "deleted_market_actors"
  • "retrofit_units"

Usage:

  • If None, all data is downloaded.
  • If a string, only the specified table is downloaded (e.g., "wind").
  • If a list, multiple tables are downloaded (e.g., ["wind", "solar"]).

TYPE: str or list or None DEFAULT: None

date
date description
"today" latest files are downloaded from marktstammdatenregister.de
"20230101" If file from this date exists locally, it is used. Otherwise it throws an error (You can only receive todays data from the server)
"existing" Deprecated since 0.16, see #616
None set date="today"

Default to None.

TYPE: None or `datetime.datetime` or str DEFAULT: None

select_date_interactively

If set to True, the user will be presented with a list of available download dates from the MaStR website and can interactively select which date to download. This allows downloading historical data instead of just the latest available data. When True, the date parameter is ignored. Defaults to False.

TYPE: bool DEFAULT: False

bulk_cleansing

If set to True, data cleansing is applied after the download (which is recommended). In its original format, many entries in the MaStR are encoded with IDs. Columns like state or fueltype do not contain entries such as "Hessen" or "Braunkohle", but instead only contain IDs. Cleansing replaces these IDs with their corresponding original entries.

TYPE: bool DEFAULT: True

keep_old_downloads

If set to True, prior downloaded MaStR zip files will be kept.

TYPE: bool DEFAULT: False

to_csv(tables=None, chunksize=500000, limit=None)

Save the database as csv files along with the metadata file. If 'tables=None' all possible tables will be exported.

PARAMETER DESCRIPTION
tables

For exporting selected tables choose from: ["wind", "solar", "biomass", "hydro", "gsgk", "combustion", "nuclear", "storage", "balancing_area", "electricity_consumer", "gas_consumer", "gas_producer", "gas_storage", "gas_storage_extended", "grid_connections", "grids", "market_actors", "market_actors_and_roles", "locations_extended", "permit", "deleted_units", "storage_units"]

TYPE: list DEFAULT: None

chunksize

Defines the chunksize of the tables export. Default value is 500.000 rows to include in each chunk.

TYPE: int DEFAULT: 500000

limit

Limits the number of exported data rows.

TYPE: int DEFAULT: None

translate()

A database can be translated only once.

Deletes translated versions of the currently connected database.

Translates currently connected database,renames it with '-translated' suffix and updates self.engine's path accordingly.

Example

from open_mastr import Mastr
import pandas as pd

db = Mastr()
db.download(data='biomass')
db.translate()

df = pd.read_sql(sql='biomass_extended', con=db.engine)
print(df.head(10))