eurovalidate 0.1.0

Python SDK for the EuroValidate API — validate EU VAT, IBAN, EORI, and company data

EuroValidate Python SDK

Official Python SDK for the EuroValidate API -- validate EU VAT numbers, IBANs, EORI numbers, and look up company data in one unified API.

Installation

pip install eurovalidate

Requires Python 3.9+.

Quick start

from eurovalidate import EuroValidate

client = EuroValidate("ev_live_your_key_here")

# Validate a VAT number
result = client.validate_vat("NL820646660B01")
print(result.valid)          # True
print(result.company_name)   # "COOLBLUE B.V."
print(result.company_address)
print(result.meta.confidence) # "HIGH"

Get your free API key at eurovalidate.com.

Usage

VAT validation

result = client.validate_vat("DE123456789")
print(result.valid, result.company_name, result.country_code)

IBAN validation

result = client.validate_iban("DE89370400440532013000")
print(result.valid, result.bank_name, result.bic)

EORI validation

result = client.validate_eori("DE328169180000040")
print(result.valid, result.company_name)

Company lookup (by LEI)

result = client.lookup_company_by_lei("724500Y6DUVHQD6OXN27")
print(result.company_name, result.registered_address)

VAT rates

rates = client.get_vat_rates("DE")
print(rates.standard_rate)  # 19.0
for rate in rates.rates:
    print(f"{rate.type}: {rate.rate}%")

# All EU countries
all_rates = client.get_all_vat_rates()

Unified validation (multiple checks, one call)

result = client.validate(
    vat="NL820646660B01",
    iban="DE89370400440532013000",
    eori="DE328169180000040",
)
print(result.vat.valid, result.iban.valid, result.eori.valid)

Account info

account = client.get_account()
print(f"Plan: {account.plan}, Used: {account.calls_used}/{account.calls_limit}")

Async client

Every method is also available as an async version:

from eurovalidate import AsyncEuroValidate

async with AsyncEuroValidate("ev_live_your_key_here") as client:
    result = await client.validate_vat("NL820646660B01")
    print(result.valid, result.company_name)

Error handling

The SDK raises typed exceptions for API errors:

from eurovalidate import EuroValidate, AuthError, RateLimitError, ValidationError

client = EuroValidate("ev_live_your_key_here")

try:
    result = client.validate_vat("INVALID")
except AuthError:
    print("Invalid API key")
except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after}s")
    print(f"Limit: {e.rate_limit.limit}, Remaining: {e.rate_limit.remaining}")
except ValidationError as e:
    print(f"Bad input: {e.detail}")

Rate-limited requests (HTTP 429) are automatically retried up to 3 times using the Retry-After header.

Exception hierarchy

• EuroValidateError -- base class for all API errors
  • AuthError -- 401 Unauthorized
  • RateLimitError -- 429 Too Many Requests
  • ValidationError -- 400 / 422 invalid input
  • NotFoundError -- 404 Not Found
  • ServerError -- 5xx server errors

All exceptions include status_code, detail, request_id, and rate_limit attributes.

Response metadata

Every result includes a meta field with data freshness information:

result = client.validate_vat("NL820646660B01")
print(result.meta.confidence)      # "HIGH", "MEDIUM", "LOW", or "UNKNOWN"
print(result.meta.source)          # "vies_live", "cache", etc.
print(result.meta.cached)          # True/False
print(result.meta.response_time_ms)
print(result.meta.last_verified)   # ISO 8601 timestamp

Configuration

client = EuroValidate(
    "ev_live_your_key_here",
    base_url="https://api.eurovalidate.com",  # default
    timeout=30.0,                              # seconds, default
)

License

MIT