geost.bro_api_read#

geost.bro_api_read(object_type: BroObject, *, bro_ids: str | list[str] = None, epsg: int = 28992, bbox: tuple[float, float, float, float] = None, geometry: GeoDataFrame = None, buffer: int | float = None, schema: dict[str, Any] = None)[source]#

Read data directly from the BRO API. This allows to read BHR-GT, BHR-P, BHR-G and CPT data from the BRO API into geost objects without having to download the data first. Note, API requests are relatively slow, so this function is not meant for bulk downloads. Also, the API is limited to 2000 objects per request, so if you request more than 2000 objects, the API will return an error.

Parameters:

  • object_type (BroObject) – Type of BRO object to read. This can be one of the following: “BHR-GT”, “BHR-GT-samples”, “BHR-P”, “BHR-G”, “CPT”, “SFR”.

  • bro_ids (str | list[str], optional (keyword only)) – List of BRO object ids to read. If not given, the bbox or geometry must be provided to select the objects to read. If given, bbox and geometry are ignored.

  • epsg (int, optional (keyword only)) – EPSG code of the coordinate reference system that the collection will be coerced to. If using a bbox for selection, this EPSG code is also used to interpret the bbox coordinates. Note that when using a geometry for selection, the geometry’s CRS is used instead unless the geometry has no CRS defined. In that case, this EPSG code is also used. The default is 28992 (RD New).

  • bbox (tuple[float, float, float, float], optional) – Bounding box (xmin, ymin, xmax, ymax) to search BRO objects within. The default is None.

  • geometry (gpd.GeoDataFrame, optional (keyword only)) – Geometry to search within. Can be any Shapely geometry object (Point, Line, Polygon), Geopandas GeoDataFrame of path to a geometry file. The function retrieve the BRO objects that are within the outermost bounds (i.e. bounding box) of the input geometry. The default is None.

  • buffer (int | float, optional (keyword only)) – Buffer distance to apply to the geometry. This increases the bounding box of the the input geometry. The default is None.

  • schema (dict[str, Any], optional (keyword only)) – XML schema to use for reading the data which describes the structure of the XML data. If not given, the function will use the default schema for the specified object_type provided by Geost (see geost.io.xml.schemas). Note that predefined schemas only retrieve the attributes that are defined in the schema but more data may be available in the requested objects. To retrieve desired attributes, you can modify the schema accordingly (see usage examples).

Returns:

Returns a subclass of geost.base.Collection depending on the object_type.

Return type:

Subclass of geost.base.Collection

Examples

Read a list of specific borehole ids from the BRO API (max 2000 objects): >>> import geost … bhrgt = geost.bro_api_read(“BHR-GT”, bro_ids=[“BHR000000339725”, “BHR000000339735”]) … bhrgt BoreholeCollection: # header = 2

Or read geological boreholes (BHR-G) within a bounding box. Note the epsg parameter is used to interpret the bbox coordinates (by default it is 28992 - RD New): >>> import geost … bbox = (126_800, 448_000, 127_800, 449_000) # xmin, ymin, xmax, ymax … bhrg = geost.bro_api_read(“BHR-G”, bbox=bbox, epsg=28992) BoreholeCollection: # header = 3

Or within shapefile containing a Polygon geometry of the same bounding box of the previous example (Point or Line geometries are also supported). Note that the epsg of the geometry is used if it has a defined CRS, otherwise the epsg parameter must be used: >>> import geost … bhrg = geost.bro_api_read(“BHR-G”, geometry=”my_polygon.shp”) BoreholeCollection: # header = 3

Or within the shapefile and applying a buffer: >>> import geost … bhrg = geost.bro_api_read(“BHR-G”, geometry=”my_polygon.shp”, buffer=500) BoreholeCollection: # header = 5

When there are no objects found, you will get an empty collection: >>> import geost … bhrg = geost.bro_api_read(“BHR-G”, bbox=[0, 0, 1, 1]) Collection: <EMPTY COLLECTION>

On this page

This Page