geost.bro_api_read#

geost.bro_api_read(object_type: BroObject, *, bro_ids: str | list[str] = None, 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-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.

  • 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: >>> import geost … bbox = (126_800, 448_000, 127_800, 449_000) # xmin, ymin, xmax, ymax … bhrg = geost.bro_api_read(“BHR-G”, bbox=bbox) 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): >>> 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