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 finds its
zone and returns typed results. 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
import asyncio
from aiodpc import AlertLevel, DpcClient, DpcError, Risk
async def main() -> None:
async with DpcClient() as client:
try:
criticality = await client.get_criticality(41.9, 12.5)
vigilance = await client.get_vigilance(
41.9, 12.5, phenomena_radius_km=50
)
except DpcError as err:
print(f"DPC data unavailable: {err}")
return
print(f"Criticality bulletin {criticality.id}")
for day in criticality.days:
print(f"{day.date} {day.zone_name}: {day.summary.alert}")
for risk, assessment in day.risks.items():
print(f" {risk.name.lower()}: {assessment.level.name}")
if (today := criticality.today()) and today.max_level >= AlertLevel.YELLOW:
print("Alert today:", today.risks[Risk.HYDROGEOLOGICAL].info)
for day in vigilance.days:
print(f"{day.date} {day.zone_name}: {day.precipitation}")
for phenomenon in day.phenomena:
print(
f" {phenomenon.category} {phenomenon.description}"
f" {phenomenon.distance_km} km {phenomenon.direction}"
)
asyncio.run(main())
Pass your own session with DpcClient(session); the client never closes a
session it did not create.
Days and expiry
Each day of a bulletin carries its calendar date and its expires time (the
midnight, Europe/Rome, that ends the day). Look days up by date instead of by
position: bulletin.day_for(date), bulletin.today() and
bulletin.tomorrow(). 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). To poll, check the latest ID and fetch the bulletin only when it changed:
from aiodpc import BulletinKind
latest = await client.latest_bulletin_id(BulletinKind.CRITICALITY)
if latest != criticality.id:
criticality = await client.get_criticality(41.9, 12.5, 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.
Municipality
With municipality="Roma", the zones that list the municipality are
considered and the one with the highest level is used; zone_name is the zone
containing the coordinates. Large municipalities span several zones.
Coverage check
await client.is_location_covered(lat, lon) returns whether the coordinates
are inside a DPC alert zone, for example to validate a configuration.
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.
Invalid arguments (coordinates, bulletin IDs) raise ValueError.
Translations and codes
The texts written by DPC are kept in Italian (Assessment.info,
Assessment.alert, VigilanceDay.precipitation,
Phenomenon.description). Codes are exposed for translation and icons:
AlertLevel, Risk (value: the DPC code, e.g. idraulico),
PhenomenonCategory (e.g. PRECIPITAZIONI) and Phenomenon.code (the DPC
id_fenomeno).
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); implementBulletinIdSourceto 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.
Credits
aiodpc derives from the DPC Alert Home Assistant integration by caiosweet (MIT license).
License
MIT, see LICENSE.
Metadata
Release files for aiodpc 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| aiodpc-0.1.0.tar.gz | 76.8 kB | With provenance | Details for aiodpc-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| aiodpc-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for aiodpc-0.1.0-py3-none-any.whl |
Total release size: 97.8 kB
Release files / aiodpc-0.1.0.tar.gz
| Download URL | aiodpc-0.1.0.tar.gz |
|---|---|
| Size | 76.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
db5e64d0321e498e6d6f15bcfb6a3508365aad79a09bb1ed58b92281c299d097
|
|
BLAKE2b-256 checksum How to use checksums |
76b968268ae9c9bac78133f8353fd1e9477b5c50b839262c43b2d5871e9630ed
|
| 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 14, 2026.
Transparency logRelease files / aiodpc-0.1.0-py3-none-any.whl
| Download URL | aiodpc-0.1.0-py3-none-any.whl |
|---|---|
| Size | 21.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
8d2ba690d4b36e0f688f399c495d729db413f76d984bcbd6c0ba1c2633b33143
|
|
BLAKE2b-256 checksum How to use checksums |
8554a6c44716446ac398292f93f4d608c50ce15093ff3eb8bec5b7cf8f2e24e6
|
| 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 14, 2026.
Transparency logSecurity for aiodpc 0.1.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.
Attestation for aiodpc-0.1.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 14, 2026.
Transparency logA 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.