API: floods, hazard, download

The top-level functions for discovering flood events and hazard layers and fetching their rasters. All are re-exported from euroflood (e.g. euroflood.floods).

The object these return is a FloodFrame.

Discover historic floods

floods

floods(
    region: Any = None,
    *,
    point: tuple[float, float] | None = None,
    radius_m: float = 0.0,
    bbox: tuple[float, float, float, float] | None = None,
    shapefile: str | Path | None = None,
    nuts: str | Sequence[str] | None = None,
    buffer_m: float = 0.0,
    crs: Any = None,
    year: int | None = None,
    start: str | int | None = None,
    end: str | int | None = None,
    level: int | None = None,
    shape: str = "exact",
    output_dir: str | Path | None = None,
    settings: Settings | None = None
) -> FloodFrame

Query historic flood events for a region (cheap; no rasters downloaded).

Parameters:

Name	Type	Description	Default
region	Any	Place name, shapely geometry, GeoDataFrame, or bbox tuple.	None
point	tuple[float, float] | None	A (lat, lon) point in WGS 84, or (x, y) in a projected crs; combine with radius_m.	None
radius_m	float	Radius in ground metres around point.	0.0
bbox	tuple[float, float, float, float] | None	A (minx, miny, maxx, maxy) bounding box in WGS 84 lon/lat, or in crs.	None
shapefile	str | Path | None	Path to a vector file used as the ROI.	None
nuts	str | Sequence[str] | None	One or more Eurostat NUTS identifiers, e.g. "NL22" (Gelderland) or ["NL22", "NL21"] (their union). Case-insensitive; the level follows from the identifier (NL country, NL2, NL22, NL225). Boundaries come from the Eurostat GISCO 1:1M files for settings.nuts_year (default 2024), downloaded once per level and cached. Find identifiers with nuts.	None
buffer_m	float	Optional extra buffer around the ROI, in ground metres.	0.0
crs	Any	Coordinate reference system of point, bbox and a bare shapely or 4-tuple region: any horizontal (geographic or projected) CRS accepted by pyproj.CRS.from_user_input, e.g. an authority string ("EPSG:28992"), an EPSG integer (3035), a WKT/PROJ string or a pyproj.CRS. Default None means WGS 84 lon/lat (EPSG:4326), i.e. today's behaviour. point is (lat, lon) in any geographic CRS and (x, y) = (easting, northing) in any projected CRS, regardless of the axis order the CRS authority declares (EPSG:3035 is northing-first in the registry but is still given as (easting, northing) here); bbox is always (minx, miny, maxx, maxy). A GeoDataFrame or vector file carries its own CRS: crs then only fills in a missing one and must agree with it otherwise. Not valid with a place name. The result is always EPSG:4326.	None
year	int | None	Keep only events in this year.	None
start	str | int | None	Keep events on/after this date ("YYYY" or "YYYY-MM-DD").	None
end	str | int | None	Keep events on/before this date ("YYYY" or "YYYY-MM-DD").	None
level	int | None	Optional NUTS level filter for place-name resolution.	None
shape	str	ROI shape derived from the resolved region: "exact" (default, the raw boundary), "bbox" (its bounding rectangle), or "hull" (its convex hull). Useful when an admin boundary follows a river or is oddly shaped; buffer_m still applies on top of the chosen shape.	'exact'
output_dir	str | Path | None	Directory the cached-download auto-detect scans (defaults to settings.output_dir). Pass the same dir you .download() to so a later query of the same area already carries the files.	None
settings	Settings | None	Optional configuration (e.g. a different cache/index version).	None

Returns:

Name	Type	Description
FloodFrame	FloodFrame	One row per flood event; .download("out/") fetches rasters.

Raises:

Type	Description
GeocodingError	If a place name cannot be resolved.
CRSError	(a GeocodingError) if crs is invalid, conflicts with the CRS of a GeoDataFrame/file, is combined with a place name, or the coordinates do not fit it.
NutsError	(a GeocodingError) if a NUTS identifier is malformed or unknown, has no published boundary, or its boundary file is unavailable offline.
FileNotFoundError	If no index is available locally and no remote index is configured (run build-index/mirror-index or set index_mode="remote").

Examples:

>>> import euroflood as ef
>>> cat = ef.floods("Zutphen")
>>> recent = cat[cat["date"] >= "2021-01-01"]
>>> recent.download("out/")
>>> ef.floods(
...     bbox=(200000, 455000, 220000, 475000), crs="EPSG:28992"
... )  # Dutch RD New metres
>>> ef.floods(
...     nuts="NL22"
... )  # a Eurostat NUTS region (Gelderland)

Query global flood hazard

hazard

hazard(
    region: Any = None,
    *,
    point: tuple[float, float] | None = None,
    radius_m: float = 0.0,
    bbox: tuple[float, float, float, float] | None = None,
    shapefile: str | Path | None = None,
    nuts: str | Sequence[str] | None = None,
    buffer_m: float = 0.0,
    crs: Any = None,
    return_period: int | list[int] | None = None,
    level: int | None = None,
    shape: str = "exact",
    output_dir: str | Path | None = None,
    settings: Settings | None = None
) -> FloodFrame

Query global flood-hazard maps by return period (CEMS-GLOFAS).

Mirrors floods exactly but takes return_period instead of a time filter. Returns a downloadable FloodFrame with one row per return period; .download("out/") writes one mosaicked, ROI-cropped hazard_RP{rp}.tif per row.

Parameters:

Name	Type	Description	Default
region	Any	Place name, shapely geometry, GeoDataFrame, or bbox tuple.	None
point	tuple[float, float] | None	A (lat, lon) point in WGS 84, or (x, y) in a projected crs; combine with radius_m.	None
radius_m	float	Radius in ground metres around point.	0.0
bbox	tuple[float, float, float, float] | None	A (minx, miny, maxx, maxy) bounding box in WGS 84 lon/lat, or in crs.	None
shapefile	str | Path | None	Path to a vector file used as the ROI.	None
nuts	str | Sequence[str] | None	One or more Eurostat NUTS identifiers, e.g. "NL22" (Gelderland) or ["NL22", "NL21"] (their union). Case-insensitive; the level follows from the identifier (NL country, NL2, NL22, NL225). Boundaries come from the Eurostat GISCO 1:1M files for settings.nuts_year (default 2024), downloaded once per level and cached. Find identifiers with nuts.	None
buffer_m	float	Optional extra buffer around the ROI, in ground metres.	0.0
crs	Any	Coordinate reference system of point, bbox and a bare shapely or 4-tuple region: any horizontal (geographic or projected) CRS accepted by pyproj.CRS.from_user_input, e.g. an authority string ("EPSG:28992"), an EPSG integer (3035), a WKT/PROJ string or a pyproj.CRS. Default None means WGS 84 lon/lat (EPSG:4326), i.e. today's behaviour. point is (lat, lon) in any geographic CRS and (x, y) = (easting, northing) in any projected CRS, regardless of the axis order the CRS authority declares (EPSG:3035 is northing-first in the registry but is still given as (easting, northing) here); bbox is always (minx, miny, maxx, maxy). A GeoDataFrame or vector file carries its own CRS: crs then only fills in a missing one and must agree with it otherwise. Not valid with a place name. The result is always EPSG:4326.	None
return_period	int | list[int] | None	One or more of 10/20/50/75/100/200/500. None returns all available return periods.	None
level	int | None	Optional NUTS level filter for place-name resolution.	None
shape	str	ROI shape derived from the resolved region: "exact" (default, the raw boundary), "bbox" (its bounding rectangle), or "hull" (its convex hull); buffer_m still applies on top.	'exact'
output_dir	str | Path | None	Directory the cached-download auto-detect scans (defaults to settings.output_dir).	None
settings	Settings | None	Optional configuration.	None

Returns:

Name	Type	Description
FloodFrame	FloodFrame	One row per return period; .download("out/") fetches maps.

Raises:

Type	Description
GeocodingError	If a place name cannot be resolved.
CRSError	(a GeocodingError) if crs is invalid, conflicts with the CRS of a GeoDataFrame/file, is combined with a place name, or the coordinates do not fit it.
NutsError	(a GeocodingError) if a NUTS identifier is malformed or unknown, has no published boundary, or its boundary file is unavailable offline.
HazardError	If the hazard tile index cannot be located or read.

Examples:

>>> import euroflood as ef
>>> ef.hazard("Zutphen", return_period=100).download(
...     "hazard/"
... )
>>> ef.hazard("Zutphen", return_period=[100, 500])
>>> ef.hazard(
...     point=(308400, 5780300),
...     radius_m=5000,
...     crs="EPSG:32632",
...     return_period=100,
... )  # a UTM 32N point: (x, y)
>>> ef.hazard(nuts=["NL22", "NL21"], return_period=100)

Find NUTS regions

nuts

nuts(
    query: str | None = None,
    *,
    level: int | None = None,
    country: str | None = None,
    geometry: bool = False,
    settings: Settings | None = None
) -> DataFrame | GeoDataFrame

Find Eurostat NUTS regions: search by name, or list by country and level.

Use it to find the identifier for floods / hazard nuts= ("Gelderland" -> NL22) or to enumerate regions to loop over (every Dutch NUTS-2 region). NUTS levels: 0 country (NL), 1 major regions (NL2), 2 basic regions (NL22), 3 small regions (NL225); an identifier's length gives its level.

Parameters:

Name	Type	Description	Default
query	str | None	A region name (accent/case-insensitive; bilingual and suffixed names and common exonyms such as "Cologne" match, and every name containing the text is listed), or a NUTS identifier, which lists that region and its descendants ("NL2" -> NL2, NL22, NL225, ...).	None
level	int | None	Keep only this NUTS level (0-3).	None
country	str | None	Keep only this two-letter country code ("NL").	None
geometry	bool	Attach the boundary polygons (downloads the GISCO per-level files the result needs, once). Without it only the 90 KB attribute table is read, so a search never downloads a boundary file.	False
settings	Settings | None	Optional configuration (nuts_year, nuts_scale, ...).	None

Returns:

Type	Description
DataFrame | GeoDataFrame	A DataFrame with NUTS_ID, LEVL_CODE, CNTR_CODE, NAME_LATN
DataFrame | GeoDataFrame	and NUTS_NAME sorted by identifier; with geometry=True a
DataFrame | GeoDataFrame	GeoDataFrame in EPSG:4326. No match is an empty frame, not an error.

Raises:

Type	Description
NutsError	If the attribute table or a boundary file is unavailable offline or fails to download.

Examples:

>>> import euroflood as ef
>>> ef.nuts("Gelderland")  # -> NL22 (level 2), NL224
>>> ef.nuts(
...     country="NL", level=2
... )  # every Dutch NUTS-2 region
>>> for nuts_id in ef.nuts(country="NL", level=2)["NUTS_ID"]:
...     ef.floods(nuts=nuts_id)
>>> ef.nuts("NL2", level=3, geometry=True).explore()

Download rasters

download

download(
    catalogue: FloodFrame,
    output_dir: str | Path | None = None,
    *,
    crop: bool = True,
    force: bool = False,
    settings: Settings | None = None,
    on_bytes: Callable[[int], None] | None = None
) -> list[Path]

Download + crop the rasters for a (possibly filtered) catalogue.

The functional equivalent of catalogue.download(...); works on any GeoDataFrame produced by floods or hazard (it routes by the collection column), even after heavy reshaping. Returns the file paths; prefer the download method (returns the catalogue itself) for the fluent, actionable workflow.

Parameters:

Name	Type	Description	Default
catalogue	FloodFrame	A catalogue from floods or hazard, or a filtered subset of one.	required
output_dir	str | Path | None	Directory for the written GeoTIFFs. Defaults to settings.output_dir.	None
crop	bool	If True (default), crop each raster to the ROI polygon.	True
force	bool	Re-download + re-crop even if the output already exists (outputs are otherwise cached and reused).	False
settings	Settings | None	Optional configuration.	None
on_bytes	Callable[[int], None] | None	Optional progress callback (n_bytes) -> None per downloaded chunk (the CLI uses it to drive a progress bar).	None

Returns:

Type	Description
list[Path]	The paths of the written GeoTIFFs: one per historic event, or one
list[Path]	hazard_RP{rp}_{roi}.tif per return period.

Raises:

Type	Description
HazardError	If a hazard mosaic/crop fails.

Examples:

>>> import euroflood as ef
>>> cat = ef.floods("Zutphen")
>>> ef.download(cat[cat["date"] >= "2021-01-01"], "out/")

Mirror data for offline use

mirror

mirror(
    target: str,
    region: Any = None,
    *,
    point: tuple[float, float] | None = None,
    radius_m: float = 0.0,
    bbox: tuple[float, float, float, float] | None = None,
    shapefile: str | Path | None = None,
    nuts: str | Sequence[str] | None = None,
    buffer_m: float = 0.0,
    crs: Any = None,
    return_period: int | list[int] | None = None,
    year: int | None = None,
    start: str | int | None = None,
    end: str | int | None = None,
    level: int | None = None,
    shape: str = "exact",
    dry_run: bool = False,
    settings: Settings | None = None
) -> MirrorResult | dict[str, MirrorResult]

Stage a data layer for offline/HPC use.

target selects what to mirror into the cache:

• "index": the flood catalogue (global; enables offline floods() queries).
• "floods": historic flood depth maps for the region (ensures the index).
• "hazard": GLOFAS hazard tiles for the region.
• "all": index + flood depths + hazard tiles for the region.

region/bbox/point/… scope the region for floods/hazard/all; crs declares the coordinate reference system of bbox/point/a bare geometry, and nuts selects Eurostat NUTS regions by identifier, both as in floods. Resolving a NUTS region caches its GISCO boundary file, so a later offline run finds it. return_period applies to hazard, year/start/end to floods. Pass dry_run=True to plan without downloading.

Returns:

Type	Description
MirrorResult | dict[str, MirrorResult]	A MirrorResult (single target) or a {layer: MirrorResult} dict ("all").

Examples:

>>> import euroflood as ef
>>> ef.mirror(
...     "hazard", bbox=(6.1, 52.0, 6.3, 52.2), return_period=100
... )
>>> ef.mirror("all", "Zutphen")

Verify a local mirror

verify

verify(
    target: str,
    region: Any = None,
    *,
    point: tuple[float, float] | None = None,
    radius_m: float = 0.0,
    bbox: tuple[float, float, float, float] | None = None,
    shapefile: str | Path | None = None,
    nuts: str | Sequence[str] | None = None,
    buffer_m: float = 0.0,
    crs: Any = None,
    return_period: int | list[int] | None = None,
    year: int | None = None,
    start: str | int | None = None,
    end: str | int | None = None,
    level: int | None = None,
    shape: str = "exact",
    deep: bool = False,
    settings: Settings | None = None
) -> MirrorReport | dict[str, MirrorReport]

Report local-mirror readiness (present/missing/corrupt) for a data layer.

target mirrors mirror (index/floods/hazard/all), and so do the ROI arguments including crs and nuts. deep re-hashes each file's sha256 against the ledger (slower, catches silent corruption). Returns a MirrorReport (or a {layer: MirrorReport} dict for "all").

Toggle offline mode

offline

offline(enabled: bool = True) -> None

Flip EuroFlood into (or out of) fully-offline mode.

Sets the master offline switch on the global settings, forcing both collections cache-only (the index COG is not streamed, hazard tiles are not fetched) and the geocoder to the local NUTS backend, the programmatic equivalent of EUROFLOOD_OFFLINE=1. Mirror your data first (see mirror).

Examples:

>>> import euroflood as ef
>>> ef.offline()  # this node has no internet
>>> ef.hazard(
...     bbox=(6.1, 52.0, 6.3, 52.2), return_period=100
... ).download()

Logging

setup_logging

setup_logging(
    level: str = "INFO",
    *,
    json: bool | None = None,
    stream: TextIO | None = None
) -> None

Configure structured logging for the euroflood logger.

Idempotent: repeated calls reset the handlers rather than stacking them. Only the euroflood logger is configured (with propagate=False), so this never attaches handlers to the root logger or changes the log level of unrelated libraries.

Parameters:

Name	Type	Description	Default
level	str	Log level name (e.g. "INFO", "DEBUG").	'INFO'
json	bool | None	Force JSON rendering (True) or console rendering (False). When None (default), auto-detect at call time: console when the output stream is a TTY, JSON otherwise.	None
stream	TextIO | None	Output stream. Defaults to stderr.	None