Metadata-Version: 2.4
Name: vatverify-rates
Version: 0.1.0
Summary: Offline VAT rates and validation for 44 countries — EU-27, UK, Switzerland, Norway, and more. Real checksum validation, not just regex.
Project-URL: Homepage, https://vatverify.dev
Project-URL: Repository, https://github.com/vatverify/vat-rates-py
Project-URL: Issues, https://github.com/vatverify/vat-rates-py/issues
Author: Miguel Guelbenzu
License: MIT
License-File: LICENSE
Keywords: checksum,eu-vat,hmrc,offline,python,vat,vat-number,vat-rates,vat-validation,vatverify,vies
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# vatverify-rates

[![PyPI](https://img.shields.io/pypi/v/vatverify-rates.svg)](https://pypi.org/project/vatverify-rates/)
[![Python Versions](https://img.shields.io/pypi/pyversions/vatverify-rates.svg)](https://pypi.org/project/vatverify-rates/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)

Offline VAT number validation and VAT rates for 44 countries. Real checksum algorithms (MOD97, MOD11, Luhn, HMRC 97-55), not just regex. Zero runtime dependencies, pure Python, fully type-annotated.

For *live* validation (VIES / HMRC / CH UID / Brønnøysund), use this package as the format/checksum pre-check in front of the hosted [vatverify API](https://vatverify.dev).

## Install

```bash
pip install vatverify-rates
```

## Usage

### Look up a rate

```python
from vatverify_rates import get_standard_rate, get_rate

get_standard_rate("DE")    # 19.0
get_standard_rate("FR")    # 20.0

rate = get_rate("DE")
# Rate(country_code='DE', country='Germany', standard=19.0, reduced=(7.0,), ...)
```

### Validate a VAT number

```python
from vatverify_rates import validate

result = validate("IE6388047V")
if result.valid:
    print("valid")
else:
    print("invalid:", result.errors)
```

### Country utilities

```python
from vatverify_rates import country_name, is_eu_member, get_flag

country_name("DE")     # 'Germany'
is_eu_member("CH")     # False
is_eu_member("DE")     # True
get_flag("FR")         # '🇫🇷'
```

### Types

```python
from vatverify_rates import Rate, ValidateResult, CountryCode
```

`Rate` and `ValidateResult` are `@dataclass(frozen=True, slots=True)`. `CountryCode` and `EUMemberCode` are `Literal` unions of ISO-2 codes.

## API

| Function | Returns |
|---|---|
| `get_rate(code)` | `Rate \| None` |
| `get_standard_rate(code)` | `float \| None` |
| `get_all_rates()` | `dict[str, Rate]` |
| `country_name(code)` | `str \| None` |
| `country_name_local(code)` | `str \| None` |
| `is_eu_member(code)` | `bool` |
| `is_known_country(code)` | `bool` |
| `get_flag(code)` | `str` (emoji or `""`) |
| `validate_format(vat, country=None)` | `bool` |
| `validate_checksum(vat, country=None)` | `bool` |
| `validate(vat, country=None)` | `ValidateResult` |
| `data_version` | `str` (ISO date of latest refresh) |

## Supported countries

| Group | Codes |
|---|---|
| EU-27 | AT, BE, BG, CY, CZ, DE, DK, EE, EL, ES, FI, FR, HR, HU, IE, IT, LT, LU, LV, MT, NL, PL, PT, RO, SE, SI, SK |
| UK & protocol | GB, XI |
| EFTA | CH, LI, NO, IS |
| Micro-states | AD |
| Candidate / other | AL, BA, ME, MK, RS, TR, MD, UA, XK, GE |

Greece uses `EL` per VIES convention. `XI` is Northern Ireland under the Brexit protocol.

## Offline vs live

Offline checks (format + checksum) catch typos and fraudulent-looking numbers, but cannot confirm a number is *registered* with a tax authority. That requires a live registry call. The hosted [vatverify API](https://vatverify.dev) handles VIES, HMRC, BFS, and Brønnøysund, with freshness-aware responses so a registry outage never breaks your checkout.

## Other languages

Same data, same functions, idiomatic per language:

- **JavaScript / TypeScript**: [`@vatverify/vat-rates`](https://www.npmjs.com/package/@vatverify/vat-rates) (source: [vat-rates-js](https://github.com/vatverify/vat-rates-js))

## License

MIT. See [LICENSE](LICENSE).
