API Documentation

BRO

bro

class brodata.bro.FileOrUrl(url_or_file, zipfile=None, timeout=5, to_file=None, redownload=True, max_retries=2, **kwargs)

A class for parsing and handling XML data from files, URLs, or zipped files.

Supports fetching XML data from local files or remote URLs. It also handles rejection checks and extracts data into object attributes. Data is parsed recursively and can be converted to a dictionary.

Instance variables are dynamically set based on the XML content.

__init__(url_or_file, zipfile=None, timeout=5, to_file=None, **kwargs): Parses XML from a URL, file, or zipped file, and initializes the object.

from_bro_id(bro_id, **kwargs): Fetches XML data from a REST service based on a given ‘bro_id’.

to_dict(): Converts instance attributes to a dictionary, excluding methods and private attributes.

brodata.bro.get_brondocumenten_per_bronhouder(index=('kvk', 'type'), timeout=5, **kwargs)

Get the number of documents per bronhouder (data owner).

Parameters:

index (str, tuple or list, optional) – The column(s) to set as the index of the resulting DataFrame. The default is “kvk” and “type”.
timeout (int or float, optional) – A number indicating how many seconds to wait for the client to make a connection and/or send a response. The default is 5.
**kwargs (dict) – Kwargs are passed onto pandas.DataFrame().

Returns:

df – A Pandas DataFrame, with one row per combination of bronhouder and data-type.

Return type:

pd.DataFrame

brodata.bro.get_bronhouders(index='kvk', **kwargs)

Get the name, kvk-number and the identifier of bronhouders (data owners).

Parameters:

index (string, optional) – The column to set as the index of the resulting DataFrame. The default is “kvk”.
**kwargs (dict) – Kwargs are passed onto pandas.read_json().

Returns:

df – A Pandas DataFrame, with one row per bronhouder.

Return type:

pd.DataFrame

brodata.bro.get_kvk_df(fn_bronhouder_kvk=None)

Read manually saved table of KVK and Organisatienaam to DataFrame.

from https://basisregistratieondergrond.nl/service-contact/formulieren/aangemeld-bro/ :param fn_bronhouder_kvk: str, filename of the file with bronhouder and kvk numbers :return: pandas DataFrame with kvk as index and column ‘Organisatienaam’ and ‘Bronhouder’

gmn

class brodata.gmn.GroundwaterMonitoringNetwork(url_or_file, zipfile=None, timeout=5, to_file=None, redownload=True, max_retries=2, **kwargs): Class to represent a Groundwater Monitoring Network (GMN) from the BRO.

brodata.gmn.cl: alias of GroundwaterMonitoringNetwork

gmw

class brodata.gmw.GroundwaterMonitoringWell(url_or_file, zipfile=None, timeout=5, to_file=None, redownload=True, max_retries=2, **kwargs)

Class to represent a Groundwater Monitoring Well (GMW) from the BRO.

This class parses XML data related to a groundwater monitoring well (GMW). It extracts details such as location, monitoring tube data, and well history and stores these in attributes.

Notes

This class extends bro.XmlFileOrUrl and is designed to work with GMW XML data, either from a file or URL.

brodata.gmw.cl: alias of GroundwaterMonitoringWell

brodata.gmw.get_data_in_extent(extent, kind='gld', tmin=None, tmax=None, combine=None, index=None, as_csv=False, qualifier=None, to_zip=None, to_path=None, redownload=False, silent=False, continue_on_error=False, sort=True, drop_duplicates=True, progress_callback=None)

Retrieve metadata and observations within a specified spatial extent.

This function fetches monitoring well characteristics, groundwater observations, and tube properties within the given spatial extent. It can combine the data for specific observation types and return either individual dataframes or a combined dataframe.

Parameters:

extent (str or sequence) – The spatial extent ([xmin, xmax, ymin, ymax]) to filter the data.
kind (str, optional) – The type of observations to retrieve. Valid values are {‘gld’, ‘gar’} for groundwater level dossier or groundwater analysis report. When kind is None, no observations are downloaded. Defaults to ‘gld’.
tmin (str or datetime, optional) – The minimum time for filtering observations. Defaults to None.
tmax (str or datetime, optional) – The maximum time for filtering observations. Defaults to None.
combine (bool, optional) – If True, combines the metadata, tube properties, and observations into a single dataframe. Defaults to False, which will change to True in a future version.
index (str, optional) – The column to use for indexing in the resulting dataframe. Defaults to None.
as_csv (bool, optional) –

If True, the measurement data is requested as CSV files instead of XML files
(only supported for ‘gld’). Defaults to False.
qualifier (str or list of str, optional) – A string or list of strings used to filter the observations. Only valid if kind is ‘gld’. Defaults to None.
to_path (str, optional) – If not None, save the downloaded files in the directory named to_path. The default is None.
to_zip (str, optional) – If not None, save the downloaded files in a zip-file named to_zip. The default is None.
redownload (bool, optional) – When downloaded files exist in to_path or to_zip, read from these files when redownload is False. If redownload is True, download the data again from the BRO-server. The default is False.
silent (bool, optional) – If True, suppresses progress logging. Defaults to False.
continue_on_error (bool, optional) – If True, continue after an error occurs during downloading or processing of individual observation data. Defaults to False.
sort (bool, optional) – If True, sort the observations. Only used if kind is ‘gld’. Defaults to True.
drop_duplicates (bool, optional) – If True, drop duplicate observations based on their timestamp. Only used if kind is ‘gld’. Defaults to True.
progress_callback (function, optional) – A callback function that takes two arguments (current, total) to report progress. If None, no progress reporting is done. Defaults to None.

Returns:

gdf (pd.DataFrame) – A dataframe containing tube properties and metadata within the specified extent.
obs_df (pd.DataFrame, optional) – A dataframe containing the observations for the specified wells. Returned only if combine is False.

Raises:

Exception – If as_csv=True and kind is not ‘gld’, or if other parameters are invalid.

brodata.gmw.get_observations(bro_ids, kind='gld', drop_references=True, silent=False, tmin=None, tmax=None, as_csv=False, tube_number=None, status=None, observation_type=None, qualifier=None, to_path=None, to_zip=None, redownload=False, zipfile=None, continue_on_error=False, sort=True, drop_duplicates=True, progress_callback=None, _files=None)

Retrieve groundwater observations for the specified monitoring wells (bro_ids).

This function fetches groundwater data for monitoring wells based on the provided parameters. It supports different types of observations, allows filtering by tube number, and can request the data in CSV format for groundwater level observations.

Parameters:

bro_ids (str or list or pd.DataFrame) – The BRO IDs of the monitoring wells for which to retrieve the data. If a DataFrame is provided, its index is used as the list of BRO IDs.
kind (str, optional) – The type of observations to retrieve. Can be one of {‘gmn’, ‘gld’, ‘gar’, ‘frd’}. Defaults to ‘gld’ (groundwater level dossier).
drop_references (bool or list of str, optional) – Specifies whether to drop reference fields in the returned data. Defaults to True, in which case ‘gmnReferences’, ‘gldReferences’, and ‘garReferences’ are removed.
silent (bool, optional) – If True, suppresses progress logging. Defaults to False.
tmin (str or datetime, optional) – The minimum time filter for the observations. Defaults to None.
tmax (str or datetime, optional) – The maximum time filter for the observations. Defaults to None.
as_csv (bool, optional) – If True, requests the observations as CSV files instead of XML-files. Only valid if kind is ‘gld’. Defaults to False.
tube_number (int, optional) – Filters observations to a specific tube number. Defaults to None.
status (str, optional) – A status string for additional filtering. Possible values are “volledigBeoordeeld”, “voorlopig” and “onbekend” Only valid if kind is ‘gld’. Defaults to None.
observation_type (str, optional) – An observation type string for additional filtering. Possible values are “reguliereMeting” and “controleMeting”. Only valid if kind is ‘gld’. Defaults to None.
qualifier (str or list of str, optional) – A qualifier string for additional filtering. Only valid if kind is ‘gld’. Defaults to None.
to_path (str, optional) – If not None, save the downloaded files in the directory named to_path. The default is None.
to_zip (str, optional) – If not None, save the downloaded files in a zip-file named to_zip. The default is None.
redownload (bool, optional) – When downloaded files exist in to_path or to_zip, read from these files when redownload is False. If redownload is True, download the data again from the BRO-servers. The default is False.
zipfile (zipfile.ZipFile, optional) – A zipfile-object. When not None, zipfile is used to read previously downloaded data from. The default is None.
continue_on_error (bool, optional) – If True, continue after an error occurs during downloading or processing of individual observation data. Defaults to False.
sort (bool, optional) – If True, sort the observations. Only used if kind is ‘gld’. Defaults to True.
drop_duplicates (bool, optional) – If True, drop duplicate observations based on their timestamp. Only used if kind is ‘gld’. Defaults to True.
progress_callback (function, optional) – A callback function that takes two arguments (current, total) to report progress. If None, no progress reporting is done. Defaults to None.

Returns:

A DataFrame containing the observations for the specified monitoring wells, where each row corresponds to an individual observation.

Return type:

pd.DataFrame

Raises:

Exception – If as_csv=True and kind is not ‘gld’, or if qualifier is provided for a kind other than ‘gld’.

brodata.gmw.get_tube_gdf(gmws, index=None)

Create a GeoDataFrame of tube properties combined with well metadata.

This function processes a DataFrame of well properties, extracts the relevant tube information, and combines them into a GeoDataFrame. The resulting GeoDataFrame contains metadata for each monitoring well and its associated tubes, with optional spatial information (coordinates) and relevant physical properties.

Parameters:

gmws (list or dict of GroundwaterMonitoringWell, or pd.DataFrame Well and tube data) – in one of the following formats: a list of GroundwaterMonitoringWell objects, a dictionary of these objects, or a DataFrame with the bro-ids of the GroundwaterMonitoringWells as the index and the column monitoringTube containing tube properties.
index (str or list of str, optional) – The column or columns to use for indexing the resulting GeoDataFrame. Defaults to [‘groundwaterMonitoringWell’, ‘tubeNumber’] if not provided.

Returns:

gdf – A GeoDataFrame containing the combined well and tube properties, with the specified index and optional geometry (spatial data) if ‘x’ and ‘y’ columns are present.

Return type:

gpd.GeoDataFrame

Notes

If ‘x’ and ‘y’ columns are present, the function creates a GeoDataFrame with point geometries based on these coordinates, assuming the EPSG:28992 (Dutch National Coordinate System) CRS.

brodata.gmw.get_tube_gdf_from_bro_ids(bro_ids, index=None, **kwargs)

Generate a GeoDataFrame of tube properties based on an iterable of gmw bro-ids.

This function downloads the GroundwaterMonitoringWell-objects to retreive data about the groundwater monitoring tubes, and combined this information in a new GeoDataFrame.

Parameters:

bro_ids (gpd.GeoDataFrame) – GeoDataFrame of well characteristics with bro-ids of the GroundwaterMonitoringWells as the index, retreived with brodata.gmw.get_characteristics.
index (str or list of str, optional) – Column(s) to use as the index for the resulting GeoDataFrame. Defaults to [‘groundwaterMonitoringWell’, ‘tubeNumber’] if not provided.

Returns:

GeoDataFrame of combined well and tube properties

Return type:

gpd.GeoDataFrame

brodata.gmw.get_tube_gdf_from_characteristics(characteristics_gdf, **kwargs)

Generate a GeoDataFrame of tube properties based on well characteristics.

This function downloads the GroundwaterMonitoringWell-objects to retreive data about the groundwater monitoring tubes, and combined this information in a new GeoDataFrame.

Parameters:

characteristics_gdf (gpd.GeoDataFrame) – GeoDataFrame of well characteristics with bro-ids of the GroundwaterMonitoringWells as the index, retreived with brodata.gmw.get_characteristics.
index (str or list of str, optional) – Column(s) to use as the index for the resulting GeoDataFrame. Defaults to [‘groundwaterMonitoringWell’, ‘tubeNumber’] if not provided.

Returns:

GeoDataFrame of combined well and tube properties

Return type:

gpd.GeoDataFrame

brodata.gmw.get_tube_observations(gwm_id, tube_number, kind='gld', sort=True, drop_duplicates=True, **kwargs)

Get the observations of a single groundwater monitoring tube.

Parameters:

gwm_id (str) – The bro_id of the groundwater monitoring well.
tube_number (int) – The tube number.
kind (str, optional) – The type of observations to retrieve. Can be one of {‘gmn’, ‘gld’, ‘gar’, ‘frd’}. Defaults to ‘gld’ (groundwater level dossier).
sort (bool, optional) – If True, sort the observations. Only used if kind is ‘gld’. Defaults to True.
drop_duplicates (bool, optional) – If True, drop duplicate observations based on their timestamp. Only used if kind is ‘gld’. Defaults to True.
**kwargs (dict) – Kwargs are passed onto get_observations.

Returns:

A DataFrame containing the observations.

Return type:

pd.DataFrame

brodata.gmw.get_well_code(bro_id)

Retrieve the well code based on a given BRO-ID and return it as plain text.

This function sends a GET request to fetch the well code associated with the specified BRO-ID. If the request fails, it logs an error message and returns None.

Parameters:: bro_id (str) – The BRO-ID for which to retrieve the associated well code.
Returns:: well_code – The well code as plain text if the request is successful. Returns None if the request fails.
Return type:: str or None

gld

class brodata.gld.GroundwaterLevelDossier(url_or_file, zipfile=None, timeout=5, to_file=None, redownload=True, max_retries=2, **kwargs)

Class to represent a Groundwater Level Dossier (GLD) from the BRO.

observation

DataFrame containing groundwater level observations with time and value columns. The data is processed and filtered based on the provided arguments.

Type:: pd.DataFrame

tubeNumber

The tube number associated with the observation.

Type:: int

groundwaterMonitoringWell

The BRO-ID of the groundwater monitoring well.

Type:: str

brodata.gld.cl: alias of GroundwaterLevelDossier

brodata.gld.drop_duplicate_observations(df, bro_id='gld', keep='first', sort=True)

Remove duplicate observations from a DataFrame based on its index.

Parameters:

df (pd.DataFrame) – The DataFrame to process.
bro_id (str, optional) – Identifier for the dataset, used in warning messages. Default is “gld”.
keep ({'first', 'last', False}, optional) – Which duplicates to mark: - ‘first’ : Mark duplicates as True except for the first occurrence. - ‘last’ : Mark duplicates as True except for the last occurrence. - False : Mark all duplicates as True. Default is ‘first’.

Returns:

DataFrame with duplicate index values removed, keeping only the rows specified by the keep parameter.

Return type:

pd.DataFrame

Warning

Logs a warning message if duplicates are found, indicating the number and total count of duplicates before removal.

brodata.gld.get_objects_as_csv(bro_id, rapportagetype='volledig', observatietype=None, to_file=None, return_contents=True, **kwargs)

Fetch a complete Groundwater Level Dossier (GLD) as a CSV (RFC 4180) file based on the provided BRO-ID. The data can be filtered by report type and observation type.

Parameters:

bro_id (str) – The BRO-ID of the Groundwater Level Dossier to fetch. It can also be a full url, which is used by the gm-services. When using a full url, the parameter rapportagetype needs to reflect the choice in the url, and the parameter observatietype is ignored.
rapportagetype (str, optional) – Type of report. The valid values are: - “volledig” : Full report - “compact” : Compact report with readable timestamps - “compact_met_timestamps” : Compact report with Unix epoch timestamps Default is “volledig”.
observatietype (str, optional) – Type of observations. The valid values are: - “regulier_beoordeeld” : Regular measurement with full evaluation (observatietype = reguliere meting en mate beoordeling = volledig beoordeeld) - “regulier_voorlopig” : Regular measurement with preliminary evaluation (observatietype = reguliere meting en mate beoordeling = voorlopig) - “controle” : Control measurement (observatietype = controle meting) - “onbekend” : Unknown evaluation (observatietype = reguliere meting en mate beoordeling = onbekend) If None, all observation types will be returned. Default is None.
to_file (str, optional) – If provided, the CSV data will be written to the specified file. If None, the function returns the CSV data as a DataFrame. Default is None.
return_contents (bool, optional) – If True, the function returns the parsed CSV data as a DataFrame. If False, the function returns None after saving the CSV to the specified file (if to_file is provided). Default is True.
**kwargs (additional keyword arguments) – Additional arguments passed to read_gld_csv.

Returns:

If successful, returns a DataFrame containing the parsed CSV data. If to_file is provided, returns None after saving the CSV to the specified file. If the request fails or returns empty data, returns None.

Return type:

pd.DataFrame or None

Notes

The function sends a GET request to the Groundwater Level Dossier API and fetches the data in CSV format. The rapportagetype and observatietype parameters can be used to filter the data.

brodata.gld.get_observations_summary(bro_id)

Fetch a summary of a Groundwater Level Dossier (GLD) in JSON format based on the provided BRO-ID. The summary includes details about the groundwater level observations, such as observation ID, start and end dates.

Parameters:: bro_id (str) – The BRO-ID of the Groundwater Level Dossier to fetch the summary for.
Raises:: Exception – If the request to the API fails or the status code is greater than 200, an exception will be raised with the error message returned by the API.
Returns:: A DataFrame containing the summary of the groundwater level observations. The DataFrame will be indexed by the observationId and include startDate and endDate columns, converted to datetime format.
Return type:: pd.DataFrame

Notes

The function sends a GET request to the REST API and processes the returned JSON data into a DataFrame. If the response contains valid startDate or endDate fields, they will be converted to datetime format using the pd.to_datetime function.

brodata.gld.get_series_as_csv(bro_id, filter_on_status_quality_control=None, asISO8601=False, to_file=None)

Get groundwater level series as a CSV, with timestamps and corresponding measurements.

This function retrieves a table with measurements for different observation types (regulier_voorlopig, regulier_beoordeeld, controle en onbekend) as columns. It is intended for applications such as the graphical visualization of groundwater levels.

Parameters:

bro_id (str) – The BRO-ID of the Groundwater Level Dossier.
filter_on_status_quality_control (str or list of str, optional) – One or more quality control statuses to filter the measurements by. Possible values are ‘onbeslist’, ‘goedgekeurd’, and ‘afgekeurd’. The default is None.
asISO8601 (bool, optional) – If True, timestamps are returned in ISO8601 format; otherwise, in Unix epoch format. The default is False.
to_file (str, optional) – If provided, the CSV data will be written to this file path. The default is None.

Returns:

A DataFrame containing the time series of measurements, with timestamps as the index. Returns None if no data is available.

Return type:

pd.DataFrame or None

brodata.gld.process_observations(df, bro_id='gld', to_wintertime=True, qualifier=None, tmin=None, tmax=None, sort=True, drop_duplicates=True)

Process groundwater level observations.

This function processes a DataFrame containing groundwater level observations, applying the following operations based on the provided parameters: - Conversion to Dutch winter time (optional). - Filtering observations based on the qualifier. - Dropping duplicate observations (optional). - Sorting the observations by time (optional).

Parameters:

df (pd.DataFrame) – DataFrame containing the groundwater level observations, with a time index and columns such as “value”, “qualifier”, etc.
bro_id (str) – The BRO-ID of the Groundwater Level Dossier being processed. Only used for logging-purposes. The default is “gld”.
to_wintertime (bool, optional) – If True, the observation times are converted to Dutch winter time by removing any time zone information and adding one hour. If to_wintertime is False, observation times are kept in CET/CEST. Default is True.
qualifier (str or list of str, optional) – If provided, the observations are filtered based on their “qualifier” column. Only rows with the specified qualifier(s) will be kept.
tmin (str or datetime, optional) – The minimum time for filtering observations. Defaults to None.
tmax (str or datetime, optional) – The maximum time for filtering observations. Defaults to None.
sort (bool, optional) – If True, the DataFrame will be sorted, see sort_observations. Default is True.
drop_duplicates (bool, optional) – If True, any duplicate observation times will be dropped, keeping only the first occurrence. Default is True.

Returns:

A DataFrame containing the processed observations, with duplicate rows (if any) removed, the time index sorted, and filtered by qualifier if applicable.

Return type:

pd.DataFrame

brodata.gld.read_gld_csv(fname, bro_id, rapportagetype, observatietype, **kwargs)

Read and process a Groundwater Level Dossier (GLD) CSV file.

This function reads a CSV file containing groundwater level observations, processes the data according to the specified report type (rapportagetype), and returns a DataFrame of the observations. The file is assumed to contain at least three columns: time, value, and qualifier. The ‘time’ column is parsed as datetime, and additional processing is applied to the data.

Parameters:

fname (str) – The path to the CSV file containing the groundwater level observations.
bro_id (str) – The BRO-ID of the Groundwater Level Dossier being processed.
rapportagetype (str) – The report type. Can be one of: - ‘volledig’: as complete as possible (not supported yet) - ‘compact’: simple format with time and value. - ‘compact_met_timestamps’: format with timestamps for each observation.
**kwargs (additional keyword arguments) – Additional arguments passed to the process_observations function.

Returns:

A DataFrame containing the processed observations with the following columns: - time: The observation time. - value: The observed groundwater level. - qualifier: The quality code of the observation. - censored_reason: Reason for censoring, if applicable. - censoring_limitvalue: Limit value for censoring, if applicable. - interpolation_type: The interpolation method used, if applicable.

Return type:

pd.DataFrame

Notes

The time column is parsed as a datetime index. If the report type is ‘compact_met_timestamps’, the time values are converted from Unix epoch time (milliseconds) to a datetime format.

brodata.gld.sort_observations(df)

Sort observations in a DataFrame by multiple criteria. Applies a multi-level sort to the input DataFrame, prioritizing the following criteria in order: 1. By the DataFrame’s DatetimeIndex in ascending order 2. By status (if present): volledigBeoordeeld before voorlopig before onbekend 3. By observation_type (if present): reguliereMeting before controleMeting

Parameters:: df (pandas.DataFrame) – DataFrame with optional ‘observation_type’ and ‘status’ columns, and a DatetimeIndex.
Returns:: Sorted DataFrame with the same structure as input.
Return type:: pandas.DataFrame

gar

class brodata.gar.GroundwaterAnalysisReport(url_or_file, zipfile=None, timeout=5, to_file=None, redownload=True, max_retries=2, **kwargs)

Class to represent a Groundwater Analysis Report (GAR) from the BRO.

laboratoryAnalysis

DataFrame containing groundwater quality observations.

Type:: pd.DataFrame

brodata.gar.cl: alias of GroundwaterAnalysisReport

brodata.gar.get_parameter_code(description, parameter_list=None): Get a parameter code from a parameter description

brodata.gar.get_parameter_list(url=None, timeout=5, to_file=None, **kwargs): Download a DataFrame with gar-parameters from the BRO

bhr

class brodata.bhr.GeologicalBoreholeResearch(url_or_file, zipfile=None, timeout=5, to_file=None, redownload=True, max_retries=2, **kwargs): Class to represent a Geological Borehole Research (BHR_G) from the BRO.

class brodata.bhr.GeotechnicalBoreholeResearch(url_or_file, zipfile=None, timeout=5, to_file=None, redownload=True, max_retries=2, **kwargs): Class to represent a Geotechnical Borehole Research (BHR_GT) from the BRO.

class brodata.bhr.PedologicalBoreholeResearch(url_or_file, zipfile=None, timeout=5, to_file=None, redownload=True, max_retries=2, **kwargs): Class to represent a Pedological Borehole Research (BHR_P) from the BRO.

brodata.bhr.bhrgt_graph(xml_file, to_file=None, timeout=5, language='nl', asNAP=False, topMv=None, bottomMv=None, topNap=None, bottomNap=None, return_fname=False)

Generate a svg-graph of a bhrgt-file (GeotechnicalBoreholeResearch).

Parameters:

xml_file (str) – The filename of the xml-file to generate a graphical representation of.
to_file (str, optional) – The filename to save the svg-file to. The default is None.
timeout (int or float, optional) – A number indicating how many seconds to wait for the client to make a connection and/or send a response. The default is 5.
language (str, optional) – DESCRIPTION. The default is “nl”.
asNAP (bool, optional) – If True, display the height of the drilling in m NAP. If False, display the height in meter below surface level. The default is False.
topMv (float, optional) – Highest point in the graph, in m below surface level (mv). Needs to be specified together with bottomMv. The default is None.
bottomMv (float, optional) – Lowest point in the graph, in m below surface level (mv). Needs to be specified together with topMv. The default is None.
topNap (float, optional) – Highest point in the graph, in m NAP. Needs to be specified together with bottomNap. The default is None.
bottomNap (float, optional) – Lowest point in the graph, in m NAP. Needs to be specified together with topNAP. The default is None.
return_fname (bool, optional) – If True, Return the filename of the svg-file. The default is False.

Returns:

A graphical representation of the svg-file or the filename of the svg-file.

Return type:

IPython.display.SVG or str

brodata.bhr.get_bro_ids_of_bronhouder(bronhouder, bhr_class=<class 'brodata.bhr.GeotechnicalBoreholeResearch'>)

Retrieve list of BRO (Basisregistratie Ondergrond) IDs for a given bronhouder.

This function sends a GET request to the REST API to fetch the BRO IDs associated with the specified bronhouder. If the request is unsuccessful, it logs an error message.

Parameters:

bronhouder (str) – The identifier for the bronhouder to retrieve the associated BRO IDs.
bhr_class (class) – The class of borehole objects. The default is GeotechnicalBoreholeResearch. Other options are PedologicalBoreholeResearch and GeologicalBoreholeResearch.

Returns:

A list of BRO IDs if the request is successful. Returns None if the request fails.

Return type:

list or None

brodata.bhr.get_characteristics(bhr_class=<class 'brodata.bhr.GeotechnicalBoreholeResearch'>, **kwargs)

Get characteristics of a set of registered objects for a given object class.

The maximum number of objects that can be retrieved is 2000 for a single request.

Parameters:

bhr_class (class) – The class of borehole objects. The default is GeotechnicalBoreholeResearch. Other options are PedologicalBoreholeResearch and GeologicalBoreholeResearch.
tmin (str or pd.Timestamp, optional) – The minimum registrationPeriod of the requested characteristics. The default is None.
tmax (str or pd.Timestamp, optional) – The maximum registrationPeriod of the requested characteristics. The default is None.
extent (list or tuple of 4 floats, optional) – Download the characteristics within extent ([xmin, xmax, ymin, ymax]). The default is None.
x (float, optional) – The x-coordinate of the center of the circle in which the characteristics are requested. The default is None.
y (float, optional) – The y-coordinate of the center of the circle in which the characteristics are requested. The default is None.
radius (float, optional) – The radius in meters of the center of the circle in which the characteristics are requested. The default is 1000.0.
epsg (str, optional) – The coordinate reference system of the specified extent, x or y, and of the resulting GeoDataFrame. The default is 28992, which is the Dutch RD-system.
to_file (str, optional) – When not None, save the characteristics to a file with a name as specified in to_file. The defaults None.
use_all_corners_of_extent (bool, optional) – Because the extent by default is given in epsg 28992, some locations along the border of a requested extent will not be returned in the result. To solve this issue, when use_all_corners_of_extent is True, all four corners of the extent are used to calculate the minimum and maximum lan and lon values. The default is True.
timeout (int or float, optional) – A number indicating how many seconds to wait for the client to make a connection and/or send a response. The default is 5.

Returns:

A GeoDataFrame contraining the characteristics.

Return type:

gpd.GeoDataFrame

Notes

Haalt de karakteristieken op van een set van registratie objecten, gegeven een kenmerkenverzameling (kenset).

De karakteristieken geven een samenvatting van een object zodat een verdere selectie gemaakt kan worden. Het past in een tweetrapsbenadering, waarbij de eerste stap bestaat uit het ophalen van de karakteristieken en de 2e stap uit het ophalen van de gewenste registratie objecten. Het resultaat van deze operatie is gemaximaliseerd op 2000.

sfr

class brodata.sfr.SoilFaceResearch(url_or_file, zipfile=None, timeout=5, to_file=None, redownload=True, max_retries=2, **kwargs)

Class to represent a Soil Face Research (SFR) from the BRO.

The configuration of the xml-file can be found at https://www.bro-productomgeving.nl/__attachments/1607470159/DO_ResponseSFR_O_DP.xml?inst-v=a371ba4a-5fb1-479c-99cb-44e36b9c21f9 (link found at https://www.bro-productomgeving.nl/bpo/latest/uitgifte-voorbeeldberichten-sfr)

brodata.sfr.cl: alias of SoilFaceResearch

cpt

class brodata.cpt.ConePenetrationTest(url_or_file, zipfile=None, timeout=5, to_file=None, redownload=True, max_retries=2, **kwargs): Class to represent a Cone Penetration Test (CPT) from the BRO.

brodata.cpt.cl: alias of ConePenetrationTest

brodata.cpt.get_graph_types(timeout=5)

Get the graph types that can be generated for CPT by the REST API of the BRO.

Parameters:: timeout (int or float, optional) – A number indicating how many seconds to wait for the client to make a connection and/or send a response. The default is 5.
Returns:: A Pandas DataFrame that contains the supported graph types, with the columns ‘name’ and ‘description’. The index of this DataFrame contains the strings that can be used for the graphType-argument in nlmod.cpt.graph().
Return type:: pd.DataFrame

brodata.cpt.graph(xml_file, graphType='cptCombinedLength', to_file=None, timeout=5, return_fname=False)

Generate a svg-graph of a cpt-file (ConePenetrationTest).

Parameters:

xml_file (str) – The filename of the xml-file to generate a graphical representation of.
graphType (str, optional) – The type of graph. Run brodata.cpt.get_graph_types() to view available graph types. The default is “cptCombinedLength”.
to_file (str, optional) – The filename to save the svg-file to. The default is None.
timeout (int or float, optional) – A number indicating how many seconds to wait for the client to make a connection and/or send a response. The default is 5.
return_fname (bool, optional) – If True, Return the filename of the svg-file. The default is False.

Returns:

A graphical representation of the svg-file or the filename of the svg-file.

Return type:

IPython.display.SVG or str

epc

class brodata.epc.ExplorationProductionConstruction(url_or_file, zipfile=None, timeout=5, to_file=None, redownload=True, max_retries=2, **kwargs): Class to represent an Exploration Production Construction (EPC) from the BRO.

brodata.epc.cl: alias of ExplorationProductionConstruction

frd

class brodata.frd.FormationResistanceDossier(url_or_file, zipfile=None, timeout=5, to_file=None, redownload=True, max_retries=2, **kwargs): Class to represent a Formation Resistance Dossier (FRD) from the BRO.

gpd

class brodata.gpd.GroundwaterProductionDossier(url_or_file, zipfile=None, timeout=5, to_file=None, redownload=True, max_retries=2, **kwargs): Class to represent a Groundwater Production Dossier (GPD) from the BRO.

brodata.gpd.cl: alias of GroundwaterProductionDossier

guf

class brodata.guf.GroundwaterUtilisationFacility(url_or_file, zipfile=None, timeout=5, to_file=None, redownload=True, max_retries=2, **kwargs)

Class to represent a Groundwater Utilisation Facility (GUF) from the BRO.

broId

The BRO identifier of the GroundwaterUtilisationFacility object.

Type:: str

objectHistory

DataFrame with the history of changes to the GUF object.

Type:: pd.DataFrame

licence

Dictionary with information about the groundwater usage licence.

Type:: dict

realisedInstallation

Dictionary with information about the realised installation.

Type:: dict

brodata.guf.cl: alias of GroundwaterUtilisationFacility

DINO

brodata.dino.get_drilling_from_dinoloket(name, column_type=None, depthReference='NAP', language='nl', return_response=False, ignore_exceptions=False)

Get a drilling from dinoloket.

This method uses the information from the webservice used by dinoloket for displaying the drilling. In this way, also lithostratigraphy-data can be returned, which is not present in the data downloaded as a csv-file by Boormonsterprofiel.

Parameters:

name (str) – The name of the drilling.
column_type (str, optional) – The type of data that is returned. Possible options are “LITHOLOGY” and “LITHOSTRATIGRAPHY” and None. If column_type is None, return a dictionary with all data. The default is None.
depthReference (str, optional) – Possible values are “NAP” and “MV”. The default is “NAP”.
language (str of length 2, optional) – Possible values are “nl” for Ducth and “en” for English. When language is not ‘nl’ or ‘en’, english is returned. The default is “nl”.
return_response (bool, optional) – Return the json-respons of the web-service without any interpretation. The default is False.
ignore_exceptions (bool, optional) – When True, ignore exceptions when things go wrong. This is usefull when requesting multiple drillings. The default is False.

Returns:

A dictionary or a DataFarme (when column_type is set) containing the drilling data.

Return type:

df or dict

brodata.dino.get_grondwaterstand(extent, config=None, timeout=5, silent=False, to_path=None, to_zip=None, redownload=False, to_gdf=True, skip=None, continue_on_error=False, progress_callback=None)

Get groundwater level (Grondwaterstand) data as a GeoDataFrame or raw objects.

Fetch Grondwaterstand data for a given geographical extent or load it from local files. Data are retrieved per monitoring location and per piezometer. Results can be returned as a GeoDataFrame or as a dictionary of Grondwaterstand objects.

Parameters:

extent (str or sequence) – The spatial extent ([xmin, xmax, ymin, ymax]) to filter the data.
config (dict, optional) – Configuration mapping for available DINO data kinds. If None, a default configuration is used.
timeout (int or float, optional) – Timeout in seconds for network requests when downloading data. The default is 5.
silent (bool, optional) – If True, suppress progress output.
to_path (str, optional) – If not None, save the downloaded files in the directory named to_path. The default is None.
to_zip (str, optional) – If not None, save the downloaded files in a zip-file named to_zip. The default is None.
redownload (bool, optional) – When downloaded files exist in to_path or to_zip, read from these files when redownload is False. If redownload is True, download the data again from the DINO-server. The default is False.
to_gdf (bool, optional) – If True (default), convert the loaded Grondwaterstand objects into a geopandas.GeoDataFrame. If False, return the raw mapping of objects.
skip (str or iterable, optional) – Name or iterable of location names to skip during download or processing.
continue_on_error (bool, optional) – If True, continue after an error occurs during downloading or processing of individual observation data. Defaults to False.
progress_callback (function, optional) – A callback function that takes two arguments (current, total) to report progress. If None, no progress reporting is done. Defaults to None.

Returns:

If to_gdf is True, returns a GeoDataFrame indexed by [‘Locatie’, ‘Filternummer’]. If False, returns a dictionary with Grondwaterstand objects.

Return type:

geopandas.GeoDataFrame or dict

Notes

When extent is a path string, this function loads local data.
When to_zip is provided, the function will create a temporary directory and archive files into the supplied ZIP.

brodata.dino.objects_to_gdf(objects, x='X-coordinaat', y='Y-coordinaat', geometry=None, index=None, to_gdf=True)

Convert a dictionary of dino-objects to a geopandas GeoDataFrame.

Parameters:

objects (dictionary of bro or dinoloket objects) – dictionary of objects to convert to (geo)dataframe
geometry (str) – name of column of geometry
x (str) – name of column of x-coordinate
y (str) – name of column of y-coordinate
index (str or list of str) – name of column to use as index
to_gdf (bool) – convert to geodataframe

Returns:

gdf – Returns a GeoDataFrame if to_gdf is True, otherwise a DataFrame

Return type:

GeoDataFrame or DataFrame

util

brodata.util.get_with_rate_limit(url, **kwargs)

Perform a GET request with BRO rate limiting.

Official limits reference: https://basisregistratieondergrond.nl/actueel/nieuws/nieuws/2024/december/opvraaglimieten-publieke-rest-services/

brodata.util.post_with_rate_limit(url, **kwargs)

Perform a POST request with BRO rate limiting.

Official limits reference: https://basisregistratieondergrond.nl/actueel/nieuws/nieuws/2024/december/opvraaglimieten-publieke-rest-services/

brodata.util.read_zipfile(fname, pathnames=None, use_bro_abbreviation=False, override_ext=None)

Read and parse files from a ZIP archive downloaded from BROloket.

Parameters:

fname (str) – Path to the ZIP file to read.
pathnames (list of str or str, optional) – List of folder names within the ZIP archive to process. If None, all unique non-root directories are processed.
use_bro_abbreviation (bool, optional) – If True, use the abbreviation of bro-objects (e.g. GMW, GLD, BHR) to store the data in the root of the returned dictionary. If False, use the first level of the folder structure in the zip-file to store the returned objects (e.g. BRO_Grondwatermonitoring, BRO_GeologischBooronderzoek). The default is False.
override_ext (str, optional) – Removed argument from read_zipfile

Returns:

Nested dictionary where the first-level keys are data-categories, and the second-level keys are file base names (bro-id or nitg-nr). The values are either parsed objects (from corresponding classes) or file objects (e.g., PIL.Image for .tif files).

Return type:

dict

Notes

For .tif files, PIL.Image objects are returned.
For other supported types, the corresponding class is instantiated with the file

and the ZipFile object.

brodata.util.request_with_rate_limit(method, url, **kwargs)

Issue an HTTP request and enforce BRO-specific rate limits when needed.

Official limits reference: https://basisregistratieondergrond.nl/actueel/nieuws/nieuws/2024/december/opvraaglimieten-publieke-rest-services/

brodata.util.wait_for_rate_limit(url)

Wait for an available request slot when calling BRO endpoints.

Official limits reference: https://basisregistratieondergrond.nl/actueel/nieuws/nieuws/2024/december/opvraaglimieten-publieke-rest-services/

plot

brodata.plot.add_lithology_legend(ax, **kwargs)

Add a custom legend to a matplotlib Axes for lithology categories.

axmatplotlib.axes.Axes: The matplotlib Axes object to which the legend will be added.
**kwargsdict, optional: Additional keyword arguments passed to ax.legend() (e.g., loc, fontsize).

Returns:: The legend object added to the axes.
Return type:: matplotlib.legend.Legend

Notes

The function reorders legend entries so that common lithology categories appear in a preferred order: - “Veen”, “Klei”, “Leem”, “Zand fijne categorie”, “Zand midden categorie”, “Zand grove categorie”, “Zand”, “Grind” These are placed at the top of the legend, while “Niet benoemd” and “Geen monster” are placed at the bottom. Duplicate labels are removed, keeping only the first occurrence.

brodata.plot.bro_lithology(df, **kwargs)

Plot lithology information from a DataFrame containing lithology data from BRO.

Parameters:

df (pandas.DataFrame) – The input DataFrame containing lithology data.
**kwargs – Additional keyword arguments passed to the underlying lithology function.

Returns:

List of matplotlib artist objects corresponding to the plotted lithology intervals.

Return type:

list

Notes

This function is a wrapper around the lithology function, mapping the DataFrame columns: - ‘upperBoundary’ as the top, - ‘lowerBoundary’ as the bot, - ‘geotechnicalSoilName’ as kind.

brodata.plot.bro_lithology_advanced(df, soil_name_column='geotechnicalSoilName', z=0.0, x=0.5, width=0.1, lithology_properties=None, ax=None, hatch_factor=2, hatch_color=(0.0, 0.0, 0.0, 0.2), hatch_linewidth=2, bro_id=None)

Plot advanced lithology data from a BRO (Basisregistratie Ondergrond) dataframe. This function visualizes soil layers with customizable colors, patterns, and hatching, creating a detailed stratigraphic column representation.

Parameters:

df (pandas.DataFrame) – DataFrame containing borehole lithology data with columns for soil names and depth boundaries.
soil_name_column (str, optional) – Name of the column containing soil classifications. Default is “geotechnicalSoilName”. Other options include “soilNameNEN5104”, “standardSoilName” or “soilName” depending on data source.
z (float, optional) – Base depth (z-coordinate) for the plot in meters. Default is 0.0.
x (float, optional) – Horizontal x-coordinate position for the lithology column. Default is 0.5.
width (float, optional) – Base width of the lithology column. Default is 0.1.
lithology_properties (dict, optional) – Dictionary mapping soil names to their visual properties (color, hatch pattern, width). If None, properties are loaded from get_bro_lithology_properties(). Default is None.
ax (matplotlib.axes.Axes, optional) – Matplotlib axes object to plot on. If None, uses current axes. Default is None.
hatch_factor (float, optional) – Scaling factor for hatch pattern density. Default is 2.
hatch_color (tuple, optional) – RGBA color tuple for hatch patterns. Default is (0.0, 0.0, 0.0, 0.2) (semi- transparent black).
hatch_linewidth (float, optional) – Line width for hatch patterns in points. Default is 2.
bro_id (str or int, optional) – BRO identifier for logging purposes. Used in warning messages. Default is None.

Returns:

List of matplotlib Rectangle patch handles for the plotted soil layers.

Return type:

list

Raises:

ValueError – If the specified soil_name_column is not present in the dataframe.

Notes

Soil names with NaN values are mapped to “grondNietGespecificeerd” (unspecified ground).
Unsupported soil names generate warning messages but do not halt execution.
Lithology properties can be overridden per layer using the lithology_properties dictionary.

brodata.plot.cone_penetration_test(cpt, figsize=(10, 10), ax=None, linewidth=1.0, ylabel='Sondeertrajectlengte')

Plot the results of a cone penetration test (CPT).

This function visualizes multiple CPT parameters (cone resistance, friction ratio, local friction, and inclination resultant) against the test depth or trajectory length. Each parameter is plotted on a separate x-axis, sharing the same y-axis.

Parameters:

cpt (pandas.DataFrame or object) – The CPT data as a DataFrame or an object with a ‘conePenetrationTest’ attribute containing the DataFrame.
figsize (tuple, optional) – Size of the figure to create if ax is not provided. Default is (10, 10).
ax (matplotlib.axes.Axes, optional) – Existing matplotlib Axes to plot on. If None, a new figure and axes are created.
linewidth (float, optional) – Width of the plot lines. Default is 1.0.
ylabel (str, optional) – Label for the y-axis. Default is “Sondeertrajectlengte”.

Returns:

List of axes objects for each parameter plotted.

Return type:

list of matplotlib.axes.Axes

Notes

The y-axis is inverted to represent increasing depth downward.
Each parameter is plotted only if its column in the DataFrame is not entirely NaN.
The function supports plotting up to four parameters: ‘coneResistance’,

‘frictionRatio’, ‘localFriction’, and ‘inclinationResultant’.

brodata.plot.descriptive_borehole_log(bhr, attr='descriptiveBoreholeLog', soil_name_column='geotechnicalSoilName', figsize=None, width=0.2, ylabel=None, nap=True)

Generate a descriptive borehole log visualization.

Parameters:

bhr (object) – Borehole object containing descriptive log data, offset, and bored interval information.
soil_name_column (str, optional) – Name of the column containing soil classifications. Default is “geotechnicalSoilName”. Other options include “soilNameNEN5104”, “standardSoilName” or “soilName” depending on data source.
figsize (tuple, optional) – Figure size as (width, height) in inches. If None, uses matplotlib default.
width (float, default=0.2) – Width of each borehole column in the plot.
ylabel (str, optional) – Label for the y-axis. If None, defaults to “z (m t.o.v. NAP)” if nap=True, or “z (m t.o.v. maaiveld)” if nap=False.
nap (bool, default=True) – If True, use NAP (Normaal Amsterdams Peil) reference level for depth. If False, use ground level (maaiveld) as reference.

Returns:

f (matplotlib.figure.Figure) – The generated figure object.
ax (matplotlib.axes.Axes) – The axes object containing the plot.

brodata.plot.dino_lithology(df, **kwargs)

Plot lithology information from a DataFrame containing lithology data from DINO.

Parameters:

df (pandas.DataFrame) – The input DataFrame containing lithology data.
**kwargs – Additional keyword arguments passed to the underlying lithology function.

Returns:

List of matplotlib artist objects corresponding to the plotted lithology intervals.

Return type:

list

Notes

This function is a wrapper around the lithology function, mapping the DataFrame columns: - ‘Bovenkant laag (m beneden maaiveld)’ as top - ‘Onderkant laag (m beneden maaiveld)’ as bot - ‘Hoofdgrondsoort’ as kind - ‘Zandmediaanklasse’ as sand_class

brodata.plot.get_bro_lithology_properties()

Retrieve a comprehensive legend dictionary for BRO (Basisregistratie Ondergrond) lithology properties. This function defines visual properties (colors and hatching patterns) for various soil and rock types used in geological mapping, including: - Primary lithologies (veen, klei, leem, zand, grind, silt) - Unspecified categories (nietBepaald, grondNietGespecificeerd) - Complex composite lithologies with width-based proportions for mixed soil types

Returns:: dict – Each property dict contains: - “color”: tuple of RGB values (normalized to 0-1 range) - “hatch”: str, optional pattern for visualization (“-”, “/”, “", “.”, “o”, “|”) - “width”: float, optional proportion value used for composite lithologies
Return type:: A dictionary mapping lithology type names (str) to their visual properties (dict or list of dict).

brodata.plot.get_dino_lithology_colors()

Retrieve the standard color mapping for DINO lithology types.

Returns:: A dictionary mapping lithology type names to their corresponding color values used for visualization in plots and maps.
Return type:: dict

brodata.plot.get_lithology_color(hoofdgrondsoort, zandmediaanklasse=None, drilling=None, colors=None)

Return the RGB color and label for a given lithology (hoofdgrondsoort).

Parameters:

hoofdgrondsoort (str or any) – The main soil type (lithology) to get the color for. If not a string (e.g., NaN), a default color is used.
zandmediaanklasse (str, optional) – The sand median class, used for further classification if hoofdgrondsoort is “zand”.
drilling (any, optional) – Optional drilling identifier, used for logging warnings.
colors (dict, optional) – Dictionary mapping lithology names to RGB color tuples (0-1). If None, uses the default lithology_colors.

Returns:

color (tuple of float) – The RGB color as a tuple of floats in the range [0, 1].
label (str) – The label for the lithology, possibly more specific for sand classes.

Notes

If the hoofdgrondsoort is not recognized, a warning is logged and a default white

color is returned. - For “zand”, the zandmediaanklasse determines the specific sand color and label. - If colors is not provided, the function uses a default color mapping.

brodata.plot.lithology(df, top, bot, kind, sand_class=None, ax=None, x=0.5, z=0.0, solid_capstyle='butt', linewidth=6, drilling=None, colors=None, **kwargs)

Plot lithology intervals from a DataFrame as vertical lines or filled spans.

Parameters:

df (pandas.DataFrame) – DataFrame containing lithology data.
top (str) – Column name in df representing the top depth of each interval.
bot (str) – Column name in df representing the bottom depth of each interval.
kind (str) – Column name in df specifying the lithology type for color mapping.
sand_class (str, optional) – Column name in df specifying sand class for color mapping (default: None).
ax (matplotlib.axes.Axes, optional) – Matplotlib axis to plot on. If None, uses current axis (default: None).
x (float, optional) – X-coordinate for vertical lines (default: 0.5). If None or not finite, uses filled spans.
z (float, optional) – Reference depth for vertical positioning (default: 0.0).
solid_capstyle (str, optional) – Cap style for vertical lines (default: “butt”).
linewidth (float, optional) – Line width for plotting (default: 6).
drilling (any, optional) – Additional drilling information for color mapping (default: None).
colors (dict, optional) – Custom color mapping for lithologies (default: None).
**kwargs – Additional keyword arguments passed to matplotlib plotting functions.

Returns:

List of matplotlib artist objects corresponding to the plotted lithology intervals.

Return type:

list

Notes

If x is provided and finite, plots vertical lines at x.
If x is None or not finite, plots filled horizontal spans between z_top and

z_bot. - Uses get_lithology_color to determine color and label for each interval.

brodata.plot.lithology_along_line(gdf, line, kind, ax=None, legend=True, max_distance=None, **kwargs)

Plot lithological drillings along a cross-sectional line.

This function visualizes subsurface lithology data from borehole records in a 2D cross-section view, based on their proximity to a specified line. It supports both ‘dino’ and ‘bro’ formatted datasets.

Parameters:

gdf (geopandas.GeoDataFrame) – GeoDataFrame containing borehole data. This typically includes geometry and lithology-related columns. Can be retrieved using, for example, brodata.dino.get_boormonsterprofiel.
line (shapely.geometry.LineString or list of tuple[float, float]) – The cross-sectional line along which to plot the lithologies. Determines the x-coordinates of the lithology logs. If max_distance is set, only boreholes within this distance from the line will be included.
kind (str) – Specifies the data source format. Must be either ‘dino’ or ‘bro’.
ax (matplotlib.axes.Axes, optional) – The matplotlib axes object to plot on. If None, uses the current axes.
legend (bool, optional) – Whether to include a legend for the lithology classes. Default is True.
max_distance (float, optional) – Maximum distance (in the same units as the GeoDataFrame’s CRS) from the line within which boreholes are included in the cross-section. If None, includes all.
**kwargs – Additional keyword arguments passed to either dino_lithology or bro_lithology.

Returns:

ax – The matplotlib axes object containing the lithology cross-section plot.

Return type:

matplotlib.axes.Axes

Raises:

Exception – If kind is not ‘dino’ or ‘bro’.