VATcomply is a free API service providing:
- VAT number validation - Validate European VAT numbers using the official VIES database
- Foreign exchange rates - Daily rates from the European Central Bank with historical data
- Visitor IP geolocation - Automatic country detection from visitor's IP address
- IBAN validation - International Bank Account Number validation
- Country & currency data - Comprehensive country and currency information
📖 Interactive API Documentation - Complete Swagger/OpenAPI schema with live testing
Validate European VAT numbers using the official VIES (VAT Information Exchange System) database.
GET /vat?vat_number=BE0123456789Response:
{
"valid": true,
"vat_number": "123456789",
"name": "COMPANY NAME",
"address": "COMPANY ADDRESS",
"country_code": "BE"
}Supported countries: All EU member states plus Northern Ireland (XI prefix)
Note: UK (GB) VAT numbers are no longer supported since Brexit (01/01/2021). Use XI prefix for Northern Ireland businesses.
Get the latest foreign exchange rates.
GET /ratesResponse:
{
"date": "2024-01-15",
"base": "EUR",
"rates": {
"USD": 1.0856,
"GBP": 0.8642,
"JPY": 156.92
}
}Rates are quoted against the Euro by default. Quote against a different currency by setting the base parameter.
GET /rates?base=USDRequest specific exchange rates by setting the symbols parameter.
GET /rates?symbols=USD,GBPGet historical rates for a specific date.
GET /rates?date=2018-01-01Combine parameters for precise data retrieval.
GET /rates?date=2018-01-01&symbols=USD,GBP&base=EURThe primary use case is client side. For instance, with money.js in the browser
let demo = () => {
let rate = fx(1).from("GBP").to("USD");
alert("£1 = $" + rate.toFixed(4));
};
fetch("https://api.vatcomply.com/rates")
.then((resp) => resp.json())
.then((data) => (fx.rates = data.rates))
.then(demo);Get country information for the visitor's IP address automatically.
GET /geolocateResponse:
{
"iso2": "US",
"iso3": "USA",
"country_code": "US",
"name": "United States",
"numeric_code": 840,
"phone_code": "+1",
"capital": "Washington",
"currency": "USD",
"tld": ".us",
"region": "Americas",
"subregion": "Northern America",
"latitude": 39.76,
"longitude": -98.5,
"emoji": "🇺🇸",
"ip": "192.168.1.1"
}Note: This endpoint uses CloudFlare headers to detect the visitor's country. Custom IP addresses are not supported.
Validate International Bank Account Numbers (IBAN).
GET /iban?iban=GB82WEST12345698765432Response:
{
"valid": true,
"iban": "GB82WEST12345698765432",
"bank_name": "Westpac Banking Corporation",
"bic": "WESTGB2L",
"country_code": "GB",
"country_name": "United Kingdom",
"checksum_digits": "82",
"bank_code": "WEST",
"branch_code": "123456",
"account_number": "98765432",
"bban": "WEST12345698765432",
"in_sepa_zone": false
}Get a list of all countries with detailed information.
GET /countriesResponse:
[
{
"iso2": "AD",
"iso3": "AND",
"name": "Andorra",
"numeric_code": 20,
"phone_code": "+376",
"capital": "Andorra la Vella",
"currency": "EUR",
"tld": ".ad",
"region": "Europe",
"subregion": "Southern Europe",
"latitude": 42.5,
"longitude": 1.5,
"emoji": "🇦🇩"
}
]Get information about all supported currencies.
GET /currenciesResponse:
{
"USD": {
"name": "United States Dollar",
"symbol": "USD"
},
"EUR": {
"name": "Euro",
"symbol": "EUR"
}
}The API includes built-in rate limiting to ensure fair usage:
- Anonymous requests: 2 requests per second
- No authentication required
- Rate limits are applied per IP address
All endpoints return appropriate HTTP status codes:
200- Success400- Bad Request (invalid parameters)404- Not Found (invalid country code, etc.)422- Validation Error (malformed data)429- Too Many Requests (rate limit exceeded)
Error Response Format:
{
"error": "Error message description"
}VATcomply API is built on Python with key technologies including:
- Django: The core web framework, utilizing asynchronous views and ORM queries for high throughput.
- Django Ninja: Powers the REST API development on top of Django.
- Pydantic: Used for robust data validation.
- APScheduler: Manages scheduled tasks, like fetching updated exchange rates.
- Httpx: An asynchronous HTTP client for making external API calls (e.g., to the European Central Bank).
- Uvicorn: ASGI servers for running the application.
This stack enables the API to handle thousands of requests per second asynchronously.
# Set up Python environment
pyenv shell 3.11.x
virtualenv env
. env/bin/activate
# Install dependencies
make pip # or: uv pip install -r requirements.in --upgrade
make freeze # or: uv pip compile requirements.in -o requirements.txt# Run migrations
make migrate # or: python manage.py migrate
# Load initial data
python manage.py load_countries # Load country data
python manage.py load_rates # Load exchange rates (historical)
python manage.py load_rates --last-90-days # Load last 90 days only# Development server
make run # or: export DEBUG=True; uvicorn vatcomply.asgi:application --reloadThe scheduler keeps exchange rates updated hourly from the European Central Bank:
- Downloads the last 90 days of data every hour
- Rates are updated around 16:00 CET on working days
- Based on daily concertation between European central banks at 14:15 CET
- On first run, downloads all historical rates if database is empty
# Create new migrations
make migrations # or: python manage.py makemigrations
# Apply migrations
make migrate # or: python manage.py migrate# Run all tests
make test # or: python manage.py test --keepdb
# Run specific tests
python manage.py test vatcomply.tests.test_rates
python manage.py test vatcomply.tests.test_rates.RatesTest
# Test with coverage
make coverage # or: coverage run manage.py test --keepdb && coverage report -mThanks for your interest in the project! All pull requests are welcome from developers of all skill levels. To get started, simply fork the master branch on GitHub to your personal account and then clone the fork into your development environment.
Madis Väin (madisvain on Github) is the original creator of the VATcomply API.
MIT