DEV Community: ValidatorAPI

Spanish Bank Codes and Postal Codes: Free Lookup Tables for Developers (2026)

ValidatorAPI — Wed, 20 May 2026 23:26:55 +0000

Working with Spanish IBANs or building an address form for Spain?

You probably need two things that are surprisingly hard to find in a clean, developer-ready format:

A bank code lookup table (what bank does 2100 in an IBAN mean?)
A province/postal code reference (what province is 28001? What autonomous community?)

I've compiled both from public sources (Banco de España, INE, Correos) into CSV and JSON files you can drop straight into your project.

Product 1: Spanish Bank Codes Database

What it solves

A Spanish IBAN looks like this:

ES91 2100 0418 4502 0005 1332
        ^^^^
        Bank code = 2100 = CaixaBank

Positions 5–8 of a Spanish IBAN are the bank code — a 4-digit identifier registered with Banco de España.

There's no free, structured database of these codes anywhere. The official source is a PDF.

What's in the file

95 bank records covering:

Big 5: Santander, BBVA, CaixaBank, Sabadell, Bankinter
Online banks: Openbank, WiZink, EVO Banco, Revolut Spain
Foreign branches: Deutsche Bank, BNP Paribas, Citibank, Barclays
Rural savings banks: Cajamar, Caja Rural de Navarra, Globalcaja...
Historic/absorbed banks: Banesto, Bankia, Banco Popular (useful for old IBANs)

Fields: bank_code, official_name, common_name, swift_bic, website, type

Code example

import json

with open('spanish_banks.json') as f:
    banks = {b['bank_code']: b for b in json.load(f)}

iban = 'ES9121000418450200051332'
bank_code = iban[4:8]
print(banks[bank_code]['common_name'])  # CaixaBank
print(banks[bank_code]['swift_bic'])    # CAHMESMMXXX

const banks = require('./spanish_banks.json');
const lookup = Object.fromEntries(banks.map(b => [b.bank_code, b]));

const iban = 'ES9121000418450200051332';
const bank = lookup[iban.slice(4, 8)];
console.log(bank.common_name);  // CaixaBank

Available on Gumroad for $19 → Spanish Bank Codes Database

Product 2: Spanish Provinces & Postal Codes Database

What it solves

Spanish postal codes encode the province in their first 2 digits:

28001 = Province 28 = Madrid
08001 = Province 08 = Barcelona
41001 = Province 41 = Sevilla

But to build a province dropdown, or map a postal code to its autonomous community, you need a lookup table that ties everything together.

What's in the files (5 files)

File	Rows	Contents
`spanish_communities.csv`	19	Autonomous communities + cities
`spanish_provinces.csv`	52	INE codes, community mapping, capitals
`spanish_major_cities.csv`	60	Cities with population tier
`spanish_postal_lookup.csv`	675	One row per postal code
`spanish_postal_data.json`	—	All data combined

Fields: provinces

ine_code       → "28"
postal_prefix  → "28"
province_name  → "Madrid"
community_name → "Comunidad de Madrid"
capital        → "Madrid"

Code examples

import csv

provinces = {
    row['postal_prefix']: row
    for row in csv.DictReader(open('spanish_provinces.csv', encoding='utf-8'))
}

postal = '08001'
p = provinces[postal[:2]]
print(p['province_name'])   # Barcelona
print(p['community_name'])  # Cataluña

# Full postal code lookup
lookup = {
    row['postal_code']: row
    for row in csv.DictReader(open('spanish_postal_lookup.csv', encoding='utf-8'))
}
print(lookup['28001']['city'])        # Madrid
print(lookup['08001']['community'])   # Cataluña

const data = require('./spanish_postal_data.json');
const provinces = Object.fromEntries(data.provinces.map(p => [p.postal_prefix, p]));

console.log(provinces['41'].province_name);   // Sevilla
console.log(provinces['41'].community_name);  // Andalucía

Available on Gumroad for $24 → Spanish Provinces & Postal Codes Database

Why not just build this yourself?

You could. The data is technically public. But:

Banco de España's bank registry is a formatted PDF
INE's postal code data requires parsing their bulk download + cleaning encoding errors
Correos' postal system doesn't expose a public API or clean CSV

For most projects, the hour+ of scraping, cleaning, and testing isn't worth it when the lookup table itself only needs to be done once.

Free alternative: the province-from-postal trick

If you only need to identify the province from a postal code — and don't need the full database — you can hardcode just the 52 prefix mappings:

PROVINCE_PREFIXES = {
    "01": "Álava", "02": "Albacete", "03": "Alicante",
    "04": "Almería", "05": "Ávila", "06": "Badajoz",
    "07": "Illes Balears", "08": "Barcelona", "09": "Burgos",
    "10": "Cáceres", "11": "Cádiz", "12": "Castellón",
    "13": "Ciudad Real", "14": "Córdoba", "15": "A Coruña",
    "16": "Cuenca", "17": "Girona", "18": "Granada",
    "19": "Guadalajara", "20": "Gipuzkoa", "21": "Huelva",
    "22": "Huesca", "23": "Jaén", "24": "León",
    "25": "Lleida", "26": "La Rioja", "27": "Lugo",
    "28": "Madrid", "29": "Málaga", "30": "Murcia",
    "31": "Navarra", "32": "Ourense", "33": "Asturias",
    "34": "Palencia", "35": "Las Palmas", "36": "Pontevedra",
    "37": "Salamanca", "38": "S.C. de Tenerife", "39": "Cantabria",
    "40": "Segovia", "41": "Sevilla", "42": "Soria",
    "43": "Tarragona", "44": "Teruel", "45": "Toledo",
    "46": "Valencia", "47": "Valladolid", "48": "Bizkaia",
    "49": "Zamora", "50": "Zaragoza", "51": "Ceuta", "52": "Melilla",
}

def province_from_postal(postal_code: str) -> str:
    return PROVINCE_PREFIXES.get(postal_code[:2], "Unknown")

print(province_from_postal("28001"))  # Madrid
print(province_from_postal("08041"))  # Barcelona

If you need community mapping, city names, or the full postal lookup — that's what the dataset is for.

Also check out the free Spanish Document Validator API for NIF/NIE/CIF/IBAN validation.

How to Validate UK VAT Numbers, NINO, Company Numbers and UTR in Any Language (2026)

ValidatorAPI — Wed, 20 May 2026 21:31:10 +0000

How to Validate UK VAT Numbers, NINO, Company Numbers and UTR in Any Language (2026)

If you're building software for the UK market, you'll eventually need to validate fiscal and identification documents. This guide covers the algorithms, code examples, and the fastest way to add validation to any project.

What are these documents?

VAT number — Tax ID for UK businesses registered for VAT. Format: GB + 9 digits (e.g. GB123456789)
NINO — National Insurance Number, used for tax and social security. Format: 2 letters + 6 digits + letter (e.g. AB123456C)
Company Number — Companies House registration number. Format: 8 digits or prefix + 6 digits (e.g. SC123456 for Scottish companies)
UTR — Unique Taxpayer Reference, used for Self Assessment. Format: 10 digits (e.g. 1234567890)

Option 1: Implement it yourself

VAT number validation (Python)

UK VAT numbers use HMRC's mod-97 checksum on the first 7 digits:

def validate_uk_vat(vat: str) -> bool:
    vat = vat.strip().upper().replace(" ", "")
    if vat.startswith("GB"):
        vat = vat[2:]
    if len(vat) not in (9, 12) or not vat.isdigit():
        return False

    digits = [int(d) for d in vat[:7]]
    weights = [8, 7, 6, 5, 4, 3, 2]
    total = sum(d * w for d, w in zip(digits, weights))
    check = int(vat[7:9])

    return check == (97 - total % 97) or check == (97 - (total + 55) % 97)

NINO validation (JavaScript)

function validateNINO(nino) {
  nino = nino.replace(/\s/g, '').toUpperCase();
  const invalidFirst = /[DFIQUV]/;
  const invalidSecond = /[DFIOQUV]/;
  const invalidPrefixes = ['BG','GB','NK','KN','NT','TN','ZZ'];

  if (!/^[A-Z]{2}\d{6}[ABCD]$/.test(nino)) return false;
  if (invalidFirst.test(nino[0])) return false;
  if (invalidSecond.test(nino[1])) return false;
  if (invalidPrefixes.includes(nino.slice(0,2))) return false;
  return true;
}

Company number validation (Python)

PREFIXES = {'SC', 'NI', 'OC', 'SO', 'FC', 'BR', 'CE', 'CS'}

def validate_company_number(number: str) -> bool:
    number = number.strip().upper()
    if number[:2] in PREFIXES:
        return len(number) == 8 and number[2:].isdigit()
    return number.isdigit() and len(number) <= 8

Option 2: Use an API (3 lines of code)

For VAT the algorithm is manageable, but NINO has 15+ edge cases and Company Numbers have 15+ prefix types. If you don't want to maintain all of this, the UK Document Validator API handles everything:

Python

import requests

r = requests.get(
    'https://uk-document-validator1.p.rapidapi.com/validate/vat',
    params={'value': 'GB123456789'},
    headers={
        'X-RapidAPI-Key': 'YOUR_API_KEY',
        'X-RapidAPI-Host': 'uk-document-validator1.p.rapidapi.com'
    }
)
print(r.json())
# {'input': 'GB123456789', 'valid': True, 'type': 'VAT', 'country': 'GB', 'formatted': 'GB123 456 789'}

JavaScript

const r = await fetch(
  'https://uk-document-validator1.p.rapidapi.com/validate/nino?value=AB123456C',
  {
    headers: {
      'X-RapidAPI-Key': 'YOUR_API_KEY',
      'X-RapidAPI-Host': 'uk-document-validator1.p.rapidapi.com'
    }
  }
);
const data = await r.json();
// { valid: true, type: 'NINO', formatted: 'AB 12 34 56 C' }

PHP

$curl = curl_init();
curl_setopt_array($curl, [
    CURLOPT_URL => 'https://uk-document-validator1.p.rapidapi.com/validate/company?value=SC123456',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'X-RapidAPI-Key: YOUR_API_KEY',
        'X-RapidAPI-Host: uk-document-validator1.p.rapidapi.com'
    ],
]);
$r = json_decode(curl_exec($curl));
// $r->company_type = "Scottish company"

API response examples

VAT:

{ "input": "GB123456789", "valid": true, "type": "VAT", "country": "GB", "formatted": "GB123 456 789" }

NINO:

{ "input": "AB123456C", "valid": true, "type": "NINO", "formatted": "AB 12 34 56 C" }

Company Number:

{ "input": "SC123456", "valid": true, "type": "COMPANY_NUMBER", "company_type": "Scottish company", "formatted": "SC123456" }

Auto-detect (any document type):

{ "input": "1234567890", "valid": true, "type": "UTR", "detected_as": "UTR", "formatted": "12345 67890" }

When to use the API vs DIY

	DIY	API
VAT validation	~15 lines	3 lines
NINO edge cases	15+ rules to implement	Included
Company prefix types	15+ prefixes	Included
UTR checksum	Complex	Included
Auto-detect document type	Extra logic	Included
Maintenance	Your problem	Automatic

Free tier: 500 requests/month. Subscribe here.

Full docs and interactive playground: uk-validation-api.vercel.app/docs

How to Validate Spanish NIF, NIE, CIF and IBAN in Any Programming Language (2026)

ValidatorAPI — Wed, 20 May 2026 19:37:39 +0000

How to Validate Spanish NIF, NIE, CIF and IBAN in Any Programming Language (2026)

If you're building software for the Spanish market, sooner or later you'll need to validate fiscal documents. This guide covers everything: how the algorithms work, code examples in 4 languages, and the fastest way to add validation to any project.

What are NIF, NIE and CIF?

NIF — Tax ID for Spanish individuals (8 digits + 1 letter, e.g. 12345678Z)
NIE — Tax ID for foreign residents in Spain (X/Y/Z + 7 digits + letter, e.g. X1234567L)
CIF — Tax ID for Spanish companies (1 letter + 7 digits + 1 control char, e.g. A28015865). Also returns the company type: S.A., S.L., Cooperative, etc.
IBAN — Bank account number, 24 characters for Spanish accounts (e.g. ES9121000418450200051332)

Option 1: Implement it yourself

NIF validation (JavaScript)

const NIF_LETTERS = 'TRWAGMYFPDXBNJZSQVHLCKE';

function validateNIF(nif) {
  nif = nif.trim().toUpperCase();
  if (nif.length !== 9) return false;
  const number = parseInt(nif.slice(0, 8), 10);
  if (isNaN(number)) return false;
  return nif[8] === NIF_LETTERS[number % 23];
}

console.log(validateNIF('12345678Z')); // true
console.log(validateNIF('12345678A')); // false

NIF validation (Python)

NIF_LETTERS = "TRWAGMYFPDXBNJZSQVHLCKE"

def validate_nif(nif: str) -> bool:
    nif = nif.strip().upper()
    if len(nif) != 9:
        return False
    try:
        number = int(nif[:8])
    except ValueError:
        return False
    return nif[8] == NIF_LETTERS[number % 23]

print(validate_nif("12345678Z"))  # True

NIF validation (PHP)

function validateNIF(string $nif): bool {
    $letters = 'TRWAGMYFPDXBNJZSQVHLCKE';
    $nif = strtoupper(trim($nif));
    if (strlen($nif) !== 9) return false;
    $number = intval(substr($nif, 0, 8));
    return $nif[8] === $letters[$number % 23];
}

var_dump(validateNIF('12345678Z')); // bool(true)

Option 2: Use an API (3 lines of code, any language)

If you don't want to implement and maintain the algorithms yourself — especially for CIF which is significantly more complex — you can use the Spain Document Validator API on RapidAPI. It's free for up to 500 requests/month.

JavaScript (fetch)

const response = await fetch(
  'https://spain-document-validator1.p.rapidapi.com/validate/nif?value=12345678Z',
  {
    headers: {
      'X-RapidAPI-Key': 'YOUR_API_KEY',
      'X-RapidAPI-Host': 'spain-document-validator1.p.rapidapi.com'
    }
  }
);
const data = await response.json();
console.log(data);
// { input: '12345678Z', valid: true, type: 'NIF' }

Python (requests)

import requests

response = requests.get(
    'https://spain-document-validator1.p.rapidapi.com/validate/cif',
    params={'value': 'A28015865'},
    headers={
        'X-RapidAPI-Key': 'YOUR_API_KEY',
        'X-RapidAPI-Host': 'spain-document-validator1.p.rapidapi.com'
    }
)
print(response.json())
# {'input': 'A28015865', 'valid': True, 'type': 'CIF', 'entity_type': 'Sociedad Anónima'}

PHP (cURL)

$curl = curl_init();
curl_setopt_array($curl, [
    CURLOPT_URL => 'https://spain-document-validator1.p.rapidapi.com/validate/iban?value=ES9121000418450200051332',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'X-RapidAPI-Key: YOUR_API_KEY',
        'X-RapidAPI-Host: spain-document-validator1.p.rapidapi.com'
    ],
]);
$response = json_decode(curl_exec($curl));
// $response->bank_name = "CaixaBank"

API response examples

NIF:

{ "input": "12345678Z", "valid": true, "type": "NIF" }

CIF:

{
  "input": "A28015865",
  "valid": true,
  "type": "CIF",
  "entity_type": "Sociedad Anónima"
}

IBAN:

{
  "input": "ES9121000418450200051332",
  "valid": true,
  "type": "IBAN",
  "country": "ES",
  "formatted": "ES91 2100 0418 4502 0005 1332",
  "bank_code": "2100",
  "branch_code": "0418",
  "bank_name": "CaixaBank"
}

When to use the API vs implementing it yourself

	DIY	API
Setup time	2-4 hours	5 minutes
Works in any language	Requires separate lib per lang	Yes
CIF entity type info	Extra work	Included
IBAN bank name lookup	Very complex	Included
Maintenance when rules change	Your problem	Automatic

The free tier (500 req/month) is enough for most small projects. Paid plans start at $9/month for 15,000 requests.

The full API documentation and interactive playground is available at spanish-validation-api.vercel.app/docs.