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 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); 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.

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)

Source distribution for aiodpc 0.1.0
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)

Table of built distributions (wheels) for aiodpc 0.1.0
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 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