Skip to main content

aiodpc

Async Python client for the open data of the Italian Civil Protection Department (Dipartimento della Protezione Civile, DPC): the national alert bulletins.

  • Bollettino di criticità idrogeologica e idraulica: the alert level (green, yellow, orange, red) of each alert zone for today and tomorrow, for the hydraulic, thunderstorm and hydrogeological risks.
  • Bollettino di vigilanza meteorologica: the expected precipitation of each vigilance zone for today, tomorrow and the day after, and the significant weather phenomena (heavy rain, wind, sea storms, frost, fog, temperatures).

Given a location (coordinates, optionally a municipality), aiodpc tells whether it has a risk and which one, or returns the bulletins of its zone, day by day. It is built on asyncio and aiohttp, has no Home Assistant dependency and is fully typed.

Installation

pip install aiodpc

Python 3.13 or later is required.

Usage

aiodpc has three levels, from the simplest to the rawest: ask whether a place has a risk, read the bulletins day by day, or get the DPC files as they are.

Is there a risk here?

import asyncio

from aiodpc import Day, DpcClient


async def main() -> None:
    async with DpcClient() as dpc:
        home = dpc.location(41.9, 12.5)

        if await home.has_risk():
            risk = await home.risk()
            print(f"Alert today: {risk}")  # Alert today: orange (hydrogeological)
            print(risk.description)  # Moderata per rischio idrogeologico
            print(f"Valid until {risk.valid_until}")

        if await home.has_risk(Day.TOMORROW):
            print(f"Alert tomorrow: {await home.risk(Day.TOMORROW)}")


asyncio.run(main())

A risk has:

  • level: an AlertLevel, green, yellow, orange or red. Levels are ordered (risk.level >= AlertLevel.ORANGE); yellow and higher are alerts.
  • types: the RiskTypes at that level: HYDRAULIC, THUNDERSTORMS, HYDROGEOLOGICAL.
  • description: the DPC summary, in Italian; valid_until: the midnight (Europe/Rome) that ends the day; day: the complete assessment of the day.

The location keeps its bulletin: it checks for a new one at most once a minute and downloads it only when DPC publishes one, so has_risk() and risk() can be called as often as needed (for example at every update of a Home Assistant coordinator).

Bulletins, day by day

from aiodpc import DpcClient, Location

ROME = Location(41.9, 12.5)

async with DpcClient() as dpc:
    alerts = await dpc.get_criticality(ROME)
    weather = await dpc.get_vigilance(ROME, phenomena_within_km=50)

for day in alerts:
    print(f"{day.date} {day.zone}: {day.level}")  # 2026-11-15 Bacini di Roma: orange
    for risk in day.risks:
        print(f"  {risk}")  # hydrogeological: orange

for day in weather:
    print(f"{day.date} {day.zone}: {day.precipitation}")  # ... Comune di Roma: moderate
    for phenomenon in day.phenomena:
        print(f"  {phenomenon}")  # wind: forti, 30.4 km WSW

A criticality day has the level of its zone and the assessment of each risk type: day.hydraulic, day.thunderstorms, day.hydrogeological (all of them in day.risks). A vigilance day has the expected precipitation (a Precipitation, from none to very_heavy) and the significant phenomena near the location. A phenomenon's type (a PhenomenonType, such as light_snow) says in English what its Italian description says, and its key, its code and position, identifies it among those of its day, from one bulletin to the next.

Pass your own session with DpcClient(session); the client never closes a session it did not create.

Days and validity

Each day carries its calendar date and valid_until, the midnight (Europe/Rome) that ends it. Look days up by date rather than by position: bulletin.today, bulletin.tomorrow, bulletin.after_tomorrow (vigilance only) or bulletin.on(date). After midnight the bulletin published the day before still answers today with its second day until DPC publishes a new one.

By default, days that are already over are not downloaded (skip_expired=False to get them all, e.g. for a past bulletin_id).

Polling

The bulletin files are large (several MB per day). dpc.location() polls efficiently for you; with the bulletins, check the latest ID and fetch the bulletin only when it changed:

from aiodpc import BulletinKind

latest = await dpc.latest_bulletin_id(BulletinKind.CRITICALITY)
if latest != alerts.id:
    alerts = await dpc.get_criticality(ROME, bulletin_id=latest)

The criticality bulletin is published every day by 16:00 (Europe/Rome) and may be re-issued later the same day ("Aggiornamento"); the vigilance bulletin by 15:00.

Several places

Each bulletin is the same file for the whole of Italy (about 18 MB a day for both). For several places, download it once with get_criticality_map() or get_vigilance_map() and read it at each place with at(), which makes no request:

criticality = await dpc.get_criticality_map()
vigilance = await dpc.get_vigilance_map()

for place in (home, office):
    print(criticality.at(place).today)
    print(vigilance.at(place, phenomena_within_km=20).today)

at() raises DpcLocationError for a place outside every zone without affecting the others. A map holds the decoded files (tens of MB): keep it only while reading it. at() does no I/O, so it can also run in an executor.

Raw DPC files (optional)

pip install "aiodpc[schema]"

The DPC files are also available as typed DTOs, with clean names for the DPC fields (zone_name for "Nome zona"):

file = await dpc.get_criticality_file()  # latest bulletin, publication day
for zone in file.features:
    print(zone.properties.zone_name, zone.properties.summary)

The DTOs are strict, which is their purpose: when DPC changes its format they raise DpcParseError saying where, e.g. Object missing required field `Nome zona` - at `$.features[1].properties` . New fields are ignored. The rest of aiodpc does not use them and keeps working when the data is incomplete. get_vigilance_file() and get_phenomena_file() cover the vigilance bulletin; aiodpc.schema decodes files fetched by other means.

Municipality

With dpc.location(41.9, 12.5, municipality="Roma") or Location(41.9, 12.5, municipality="Roma"), the zones that list the municipality within 60 km of the coordinates are considered and the one with the highest level is used; zone is the zone containing the coordinates. Large municipalities span several zones.

DPC lists the municipalities by name, and a few names belong to two municipalities far apart, such as Peglio, in Lombardy and in the Marche: the zones far from the coordinates list the other one. When no zone near the coordinates lists the municipality, the zone containing them is used, with a warning.

In South Tyrol either the Italian or the German name works ("Bolzano" or "Bozen"), although DPC writes them as "Bolzano/Bozen" in the criticality bulletin and as "Bolzano" in the vigilance bulletin.

Coverage check

await dpc.is_location_covered(Location(lat, lon)) returns whether the coordinates are inside a DPC alert zone, for example to validate a configuration.

await dpc.get_alert_zone(Location(lat, lon)) returns the alert zone of the coordinates with its municipalities (zone.name, zone.municipalities), for example to let a user pick a municipality, and raises DpcLocationError when the coordinates are in no zone.

Errors

All errors derive from DpcError:

  • DpcConnectionError: network error, HTTP error status or timeout.
  • DpcParseError: invalid JSON or unexpected data format.
  • DpcLocationError: the location is not inside any zone of the bulletin.
  • DpcNoDataError: no published bulletin covers the requested day.

Invalid arguments (coordinates, bulletin IDs) raise ValueError.

Translations and codes

AlertLevel, Precipitation, RiskType and PhenomenonCategory print as English codes (orange, very_heavy, hydrogeological, wave_motion), ready to be used as translation keys; Phenomenon.code is the DPC id_fenomeno. The texts written by DPC are kept in Italian (description).

Low-level API

  • aiodpc.parsers: pure parsing functions taking the decoded GeoJSON, to parse one download for several locations or to test without network.
  • aiodpc.urls: URLs of the bulletin files.
  • aiodpc.discovery: the latest bulletin ID is read from the DPC map pages by default (MapPageIdSource); implement BulletinIdSource to use another source.

Data source and attribution

The data is published by the Dipartimento della Protezione Civile on mappe.protezionecivile.gov.it and GitHub (pcm-dpc/DPC-Bollettini-Criticita-Idrogeologica-Idraulica, pcm-dpc/DPC-Bollettini-Vigilanza-Meteorologica) under the Creative Commons Attribution 4.0 International (CC BY 4.0) license. Applications showing the data must credit:

Dipartimento della Protezione Civile – Presidenza del Consiglio dei Ministri

The text is available as aiodpc.ATTRIBUTION.

This project is not affiliated with or endorsed by DPC. The bulletins are official, but this library is not: for safety decisions, always refer to the official DPC and regional channels.

Development

python -m venv .venv && . .venv/bin/activate
pip install --editable . --group dev   # pip >= 25.1
ruff format --check . && ruff check .
mypy
pytest --cov

The tests never reach DPC: a local HTTPS server answers for the DPC hosts. tests/fixtures/real holds unmodified excerpts of real bulletins to guard the data format.

To release, set __version__ in src/aiodpc/__init__.py, describe the changes in a ## [X.Y.Z] - Unreleased section of CHANGELOG.md, commit, then run ./publish.sh X.Y.Z (--dry-run first to preview). It creates the GitHub release with the changelog notes, and the release workflow publishes to PyPI.

Credits

aiodpc derives from the DPC Alert Home Assistant integration by caiosweet (MIT license).

License

MIT, see LICENSE.

Metadata

Release files for aiodpc 0.6.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for aiodpc 0.6.0
File Size Uploaded Provenance Actions
aiodpc-0.6.0.tar.gz 98.1 kB With provenance Details for aiodpc-0.6.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for aiodpc 0.6.0
File Interpreter ABI Platform Actions
aiodpc-0.6.0-py3-none-any.whl Python 3 none any Details for aiodpc-0.6.0-py3-none-any.whl

Total release size: 134.7 kB

Release files / aiodpc-0.6.0.tar.gz

Download URL aiodpc-0.6.0.tar.gz
Size 98.1 kB
Tags Source
SHA-256 checksum
How to use checksums
6f6552dddc2d9624e1f7b83132ca451033ba237a619f2db37329c55a1371e288
BLAKE2b-256 checksum
How to use checksums
fc1124fe94f141bc01cd8fe0c883be90b5c4f974dbf816bd9ad18240e2f9e263
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.

Transparency log

Release files / aiodpc-0.6.0-py3-none-any.whl

Download URL aiodpc-0.6.0-py3-none-any.whl
Size 36.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
b83855ca90829987469c70cc049ff9f84b0d34a37c2a497c8d3f2f2d97d02c82
BLAKE2b-256 checksum
How to use checksums
538b632ed3468486d584b4b1e41a47347c5a8d6439aa733c9d6652ad6d35446e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.

Transparency log

Security for aiodpc 0.6.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for aiodpc-0.6.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page