ispra-idrogeo

ispra-idrogeo is a small, typed, async Python library for IdroGEO, the platform where ISPRA (Italy's national environmental agency) publishes what it knows about landslides and floods in Italy. A script can download the national landslide inventory and the hazard maps, keep them up to date, and ask the IdroGEO API for risk figures about any region, province or town. No browser, no copy-pasted links, no account.

async with IdroGEO() as idrogeo:
    folder = await idrogeo.fetch(opendata("frane_piff"))  # 721,365 landslides, one point each

• Getting started

  Install, download your first layer, look at it, ask the API.

• Datasets

  Every open-data layer and mosaic, for Italy, a region or a province.

• AI agents

  idrogeo-mcp: the same data as MCP tools for Claude and other agents, locally or over HTTP.

• Roadmap & AI

  Where the project goes next: improvements and AI features, prioritised.

pip install ispra-idrogeo            # downloads, API, the idrogeo command
pip install "ispra-idrogeo[geo]"     # + GeoDataFrames and GeoParquet
pip install "ispra-idrogeo[mcp]"     # + the MCP server for AI agents

What is IdroGEO, in 30 seconds

Italy is one of the European countries most exposed to landslides and floods. For decades, ISPRA and the regions have mapped every landslide they found into one national database, IFFI (Inventario dei Fenomeni Franosi in Italia), and the river basin authorities have drawn hazard maps (the PAI plans) of where the ground may slide and where rivers may flood. ISPRA joins the regional maps into national mosaics, and puts everything on IdroGEO: a web map, open-data files and a public REST API.

flowchart LR
    R["🗺️ Regions and<br/>basin authorities<br/>surveys · PAI plans"] --> I["ISPRA<br/>IFFI inventory<br/>national mosaics"]
    I --> W["IdroGEO<br/>open data (daily ZIPs)<br/>REST API"]
    W -->|ispra-idrogeo| Y["📁 Shapefiles / GeoJSON<br/>on your disk"]
    W -->|ispra-idrogeo| J["🧾 JSON<br/>risk figures, code lists"]
    Y --> U["Your work<br/>GIS · models · dashboards"]
    J --> U

Some of what is in there, straight from the API:

Italy, November 2026
Landslides mapped in IFFI	721,365
Land in high or very high landslide hazard (PAI P3 + P4)	9.5 % of the country, 28,801 km²
People living there	1.28 million
People living in areas that can flood once in 100–200 years (P2)	6.8 million, 11.5 % of the population
Dated landslide events recorded since 2018	1,290

What this library does

	Feature	In plain words
📦	Every open-data file	IFFI points, polygons and lines, diffuse-landslide areas, deep-seated deformations, dated events, reports, the two national hazard mosaics, the monitoring readings.
🗺️	Italy or one area	The whole country, or one of 19 regions, or a province that publishes on its own (Bolzano, Trento, the Sicilian ones). Shapefile or GeoJSON.
💾	A folder that stays	Files go to a persistent folder and are unpacked next to themselves, ready for GeoPandas or QGIS.
🔁	Download once, then only what changed	Each file remembers its ETag and Last-Modified. The next run asks "changed?" and gets a 304 for a few hundred bytes.
🛡️	Never half a file	Downloads stream to .part and are renamed when complete; ZIPs unpack beside the old folder and are swapped in whole. Memory stays flat even for 1.2 GB.
📊	The REST API	Landslide counts and hazard and risk indicators for Italy, macro-regions, regions, provinces, municipalities; every municipality at once, kept on disk; full landslide records; monitoring sites and webcams; code lists; paged searches.
🔄	Retries built in	Network errors, 429 and 5xx are retried with exponential backoff. Bring your own httpx.AsyncClient if you want to tune it.
🧪	Pure functions too	URL builders, request builders and parsers have no network, for your own HTTP stack.

One dependency: httpx.

Who is it for

• Researchers and students in geology, hydrology, civil engineering and remote sensing who want IFFI or PAI in a notebook.
• GIS analysts and data engineers who keep a copy of the national layers and want it refreshed every night without downloading 3 GB every night.
• Civil protection, planning and infrastructure teams who need the risk figures of a town, a province or a region, from a script.
• Journalists and civic-tech projects telling the story of landslides and floods in Italy with numbers you can check.

It started inside Limen, a multi-hazard risk monitor for Italy, where IFFI landslides and PAI hazard are inputs of a landslide-risk model, and was extracted so that anyone can use it.

Data licence and credits

Unless stated otherwise, ISPRA publishes its data under CC BY 4.0 (note legali). Anything you publish from it must credit the source, for example:

Source: ISPRA — IdroGEO, Italian landslide inventory (IFFI) and national hazard mosaics.

The two hazard mosaics you download state otherwise: the licence PDF in each ZIP says CC BY-SA 4.0, so data you derive from them must be shared under the same licence, with these citations (ispra_idrogeo.warehouse.SOURCES):

ISPRA - Mosaicatura nazionale delle aree a pericolosità da frana PAI (v. 4.0 – 2020-2021), https://idrogeo.isprambiente.it

ISPRA - Mosaicatura delle aree a pericolosità idraulica (v. 5.0 – 2020), https://idrogeo.isprambiente.it

ISPRA adds that the mosaics are technical and scientific works updated every few years: the maps with legal value are those of the basin district authorities and of the provinces of Trento and Bolzano.

This library only downloads the data. The figures in this README are drawn from IdroGEO API answers of 3 November 2026 (redraw them with uv run python docs/make_figures.py); the region map is a schematic tile map, not a geographic one.

Code: Apache-2.0. Extracted from Limen.

If this project is useful to you, a ⭐ on GitHub helps others find it.