portugal-vehicle-tax

Portuguese vehicle-tax calculators — ISV (Imposto Sobre Veículos, the one-off import/registration tax) and IUC (Imposto Único de Circulação, the annual road tax) — as a zero-dependency, pure-Python library.

Maintained by Clara Cars and used in production behind the public API at https://claracars.pt/api/public. Source: claracarspt/calcs.

A maintained estimate, cross-checked against the official AT simulator; not the official AT figure. These calculators are periodically verified against the Autoridade Tributária (AT) simulator and public tax tables — they are not the official AT number and not a substitute for the AT simulator or a licensed despachante. Tax tables change every year; verify before you rely on a euro amount.

Install

pip install portugal-vehicle-tax

Requires Python 3.10+. No runtime dependencies.

Usage

from portugal_vehicle_tax import isv, iuc

# ISV — 2016 diesel, 1950 cc, 130 g/km CO2, 10.2 years old, used EU import
r = isv.compute_isv("passenger", cc=1950, co2=130, fuel="diesel",
                    age_years=10.2, year=2016, from_eu=True, used=True)
print(r["isv"])          # 1832.92
print(r["breakdown"])    # itemised like the official AT "Demonstração"

# IUC — annual road tax for the same car
print(iuc.compute(cc=1950, co2=130, fuel="diesel", year=2016)["iuc"])   # 278.85

# Electric → exempt from both
isv.compute_isv("passenger", fuel="electric")   # {'isv': 0.0, 'exempt': True, ...}

ISV — isv.compute_isv(category, cc, co2, fuel, age_years, year, ...)

Returns a dict with isv, exempt, table, breakdown (line-by-line AT demonstração), age_reduction_pct, and a note where a caveat applies.

IUC — iuc.compute(cc, co2, fuel, year, vehicle_type="passenger")

Categoria B (cars ≥2007, cc+CO₂), Categoria A (<2007, cc × year-band), Categoria E (motorcycles). For goods vehicles use iuc.compute_iuc(vehicle_type, cc, co2, fuel, year, peso_bruto=...) (Categorias C/D, by gross weight).

Correctness self-check

python -m pytest -q          # or: python tests/test_calc.py

Ships a golden case table (petrol, diesel with age reduction, electric-exempt, the €100 minimum, PHEV reduction) frozen against the canonical Clara Cars logic. Any drift fails.

Related

• Live API (key-free): https://claracars.pt/api/public/isv?cc=1950&co2=130&fuel=diesel&year=2016 — returns both ISV and IUC.
• JS/TS SDK: portugal-vehicle-tax on npm
• PHP SDK: claracars/portugal-vehicle-tax on Packagist
• MCP server: claracarspt/mcp

MIT © Clara Cars