trenitalia-api

Python client (sync + async) for the public ViaggiaTreno (Trenitalia) API.

Install

uv add git+ssh://git@git.homelab.devncode.it:2222/marco/trenitalia-api.git

Example

from trenitalia_api import Client

with Client() as c:
    r = c.trains.search(9642)
    status = c.trains.status(r.train_id, r.train_number, r.timestamp)
    print(f"{status.origin} → {status.destination} ({status.delay} min)")

Same interface, async:

import asyncio
from trenitalia_api import AsyncClient

async def main():
    async with AsyncClient() as c:
        r = await c.trains.search(9642)
        status = await c.trains.status(r.train_id, r.train_number, r.timestamp)
        print(status)

asyncio.run(main())

Service alerts: client.alerts.list().

Look up stations and check live timetables:

with Client() as c:
    matches = c.stations.autocomplete("moncalieri")
    detail = c.stations.detail(matches[0].station_id)
    for t in c.stations.departures(detail.station_id):
        print(t.scheduled_departure, t.train_label, "→", t.destination)

Errors (network, 404, malformed payload) raise an exception. They all inherit from TrenitaliaError. See trenitalia_api/exceptions.py.

Test

uv run pytest                                    # unit, 80% coverage gate
uv run pytest tests/integration -m integration   # against the live API (optional)