python-stdnum

A Python module to parse, validate and reformat standard numbers and codes in different formats. It contains a large collection of number formats.

Basically any number or code that has some validation mechanism available or some common formatting is eligible for inclusion in this library.

https://arthurdejong.org/python-stdnum/

Common Interface

Most of the number format modules implement the following functions:

module.validate(number)

Validate the number and return a compact, consistent representation of the number or code. If the validation fails, an exception is raised that indicates the type of error.

Raises:

ValidationError – When the specified number is invalid

Returns:

str – A compact (canonical) representation of the number

module.is_valid(number)

Return either True or False depending on whether the passed number is in any supported and valid form and passes all embedded checks of the number. This function should never raise an exception.

Returns:

bool – True if validated, False otherwise

module.compact(number)

Return a compact representation of the number or code. This function generally does not do validation but may raise exceptions for wildly invalid numbers.

Returns:

str – The compacted number

module.format(number)

Return a formatted version of the number in the preferred format. This function generally expects to be passed a valid number or code and may raise exceptions for invalid numbers.

Returns:

str – A formatted number

The check digit modules generally also provide the following functions:

module.checksum(number)

Calculate the checksum over the provided number. This is generally a number that can be used to determine whether the provided number is valid. It depends on the algorithm which checksum is considered valid.

Returns:

int – A numeric checksum over the number

module.calc_check_digit(number)

Calculate the check digit that should be added to the number to make it valid.

Returns:

str – A check digit that can be appended

Apart from the above, the modules may add extra parsing, validation or conversion functions.

Helper functions and modules

exceptions

Collection of exceptions.

stdnum.get_cc_module(cc, name)

Find the country-specific named module.

Searches the stdnum collection of modules for a number format for a particular country. name may be an aliased name. For example:

>>> from stdnum import get_cc_module
>>> mod = get_cc_module('nl', 'vat')
>>> mod
<module 'stdnum.nl.btw' from '...'>
>>> mod.validate('004495445B01')
'004495445B01'

Will return None if no module could be found. The generic names that are currently in use:

  • 'vat' for value added tax numbers

  • 'businessid' for generic business identifiers (although some countries may have multiple)

  • 'personalid' for generic personal identifiers (some countries may have multiple, especially for tax purposes)

  • 'postal_code' for address postal codes

Generic check digit algorithms

damm

The Damm algorithm.

iso7064

Collection of the ISO 7064 algorithms.

luhn

The Luhn and Luhn mod N algorithms.

verhoeff

The Verhoeff algorithm.

Available formats

ad.nrt

NRT (Número de Registre Tributari, Andorra tax number).

al.nipt

NIPT, NUIS (Numri i Identifikimit për Personin e Tatueshëm, Albanian tax number).

ar.cbu

CBU (Clave Bancaria Uniforme, Argentine bank account number).

ar.cuit

CUIT (Código Único de Identificación Tributaria, Argentinian tax number).

ar.dni

DNI (Documento Nacional de Identidad, Argentinian national identity nr.).

at.businessid

Austrian Company Register Numbers.

at.postleitzahl

Postleitzahl (Austrian postal code).

at.tin

Abgabenkontonummer (Austrian tax identification number).

at.uid

UID (Umsatzsteuer-Identifikationsnummer, Austrian VAT number).

at.vnr

VNR, SVNR, VSNR (Versicherungsnummer, Austrian social security number).

au.abn

ABN (Australian Business Number).

au.acn

ACN (Australian Company Number).

au.tfn

TFN (Australian Tax File Number).

be.bis

BIS (Belgian BIS number).

be.iban

Belgian IBAN (International Bank Account Number).

be.nn

NN, NISS, RRN (Belgian national number).

be.vat

BTW, TVA, NWSt, ondernemingsnummer (Belgian enterprise number).

bg.egn

EGN (ЕГН, Единен граждански номер, Bulgarian personal identity codes).

bg.pnf

PNF (ЛНЧ, Личен номер на чужденец, Bulgarian number of a foreigner).

bg.vat

VAT (Идентификационен номер по ДДС, Bulgarian VAT number).

bic

BIC (ISO 9362 Business identifier codes).

bitcoin

Bitcoin address.

br.cnpj

CNPJ (Cadastro Nacional da Pessoa Jurídica, Brazilian company identifier).

br.cpf

CPF (Cadastro de Pessoas Físicas, Brazilian national identifier).

by.unp

УНП, UNP (Учетный номер плательщика, the Belarus VAT number).

ca.bc_phn

BC PHN (British Columbia Personal Health Number).

ca.bn

BN (Canadian Business Number).

ca.sin

SIN (Canadian Social Insurance Number).

casrn

CAS RN (Chemical Abstracts Service Registry Number).

cfi

CFI (ISO 10962 Classification of Financial Instruments).

ch.esr

ESR, ISR, QR-reference (reference number on Swiss payment slips).

ch.ssn

Swiss social security number ("Sozialversicherungsnummer").

ch.uid

UID (Unternehmens-Identifikationsnummer, Swiss business identifier).

ch.vat

VAT, MWST, TVA, IVA, TPV (Mehrwertsteuernummer, the Swiss VAT number).

cl.rut

RUT (Rol Único Tributario, Chilean national tax number).

cn.ric

RIC No.

cn.uscc

USCC (Unified Social Credit Code, 统一社会信用代码, China tax number).

co.nit

NIT (Número De Identificación Tributaria, Colombian identity code).

cr.cpf

CPF (Cédula de Persona Física, Costa Rica physical person ID number).

cr.cpj

CPJ (Cédula de Persona Jurídica, Costa Rica tax number).

cr.cr

CR (Cédula de Residencia, Costa Rica foreigners ID number).

cu.ni

NI (Número de identidad, Cuban identity card numbers).

cusip

CUSIP number (financial security identification number).

cy.vat

Αριθμός Εγγραφής Φ.Π.Α.

cz.bankaccount

Czech bank account number.

cz.dic

DIČ (Daňové identifikační číslo, Czech VAT number).

cz.rc

RČ (Rodné číslo, the Czech birth number).

de.handelsregisternummer

Handelsregisternummer (German company register number).

de.idnr

IdNr (Steuerliche Identifikationsnummer, German personal tax number).

de.stnr

St.-Nr.

de.vat

Ust ID Nr.

de.wkn

Wertpapierkennnummer (German securities identification code).

dk.cpr

CPR (personnummer, the Danish citizen number).

dk.cvr

CVR (Momsregistreringsnummer, Danish VAT number).

do.cedula

Cedula (Dominican Republic national identification number).

do.ncf

NCF (Números de Comprobante Fiscal, Dominican Republic receipt number).

do.rnc

RNC (Registro Nacional del Contribuyente, Dominican Republic tax number).

dz.nif

NIF, sometimes N.I.F.

ean

EAN (International Article Number).

ec.ci

CI (Cédula de identidad, Ecuadorian personal identity code).

ec.ruc

RUC (Registro Único de Contribuyentes, Ecuadorian company tax number).

ee.ik

Isikukood (Estonian Personal ID number).

ee.kmkr

KMKR (Käibemaksukohuslase, Estonian VAT number).

ee.registrikood

Registrikood (Estonian organisation registration code).

eg.tn

Tax Registration Number (الرقم الضريبي, Egypt tax number).

es.ccc

CCC (Código Cuenta Corriente, Spanish Bank Account Code)

es.cif

CIF (Código de Identificación Fiscal, Spanish company tax number).

es.cups

CUPS (Código Unificado de Punto de Suministro, Spanish meter point number).

es.dni

DNI (Documento Nacional de Identidad, Spanish personal identity codes).

es.iban

Spanish IBAN (International Bank Account Number).

es.nie

NIE (Número de Identificación de Extranjero, Spanish foreigner number).

es.nif

NIF (Número de Identificación Fiscal, Spanish VAT number).

es.postal_code

Postcode (the Spanish postal code).

es.referenciacatastral

Referencia Catastral (Spanish real estate property id)

eu.at_02

SEPA Identifier of the Creditor (AT-02).

eu.banknote

Euro banknote serial numbers.

eu.ecnumber

EC Number (European Community number).

eu.eic

EIC (European Energy Identification Code).

eu.nace

NACE (classification for businesses in the European Union).

eu.oss

OSS (European VAT on e-Commerce - One Stop Shop).

eu.vat

VAT (European Union VAT number).

fi.alv

ALV nro (Arvonlisäveronumero, Finnish VAT number).

fi.associationid

Finnish Association Identifier.

fi.hetu

HETU (Henkilötunnus, Finnish personal identity code).

fi.veronumero

Veronumero (Finnish individual tax number).

fi.ytunnus

Y-tunnus (Finnish business identifier).

figi

FIGI (Financial Instrument Global Identifier).

fo.vn

V-number (Vinnutal, Faroe Islands tax number).

fr.nif

NIF (Numéro d'Immatriculation Fiscale, French tax identification number).

fr.nir

NIR (French personal identification number).

fr.siren

SIREN (a French company identification number).

fr.siret

SIRET (a French company establishment identification number).

fr.tva

n° TVA (taxe sur la valeur ajoutée, French VAT number).

gb.nhs

NHS (United Kingdom National Health Service patient identifier).

gb.sedol

SEDOL number (Stock Exchange Daily Official List number).

gb.upn

UPN (English Unique Pupil Number).

gb.utr

UTR (United Kingdom Unique Taxpayer Reference).

gb.vat

VAT (United Kingdom (and Isle of Man) VAT registration number).

gh.tin

TIN (Taxpayer Identification Number, Ghana tax number).

gn.nifp

NIFp (Numéro d'Identification Fiscale Permanent, Guinea tax number).

gr.amka

AMKA (Αριθμός Μητρώου Κοινωνικής Ασφάλισης, Greek social security number).

gr.vat

FPA, ΦΠΑ, ΑΦΜ (Αριθμός Φορολογικού Μητρώου, the Greek VAT number).

grid

GRid (Global Release Identifier).

gs1_128

GS1-128 (Standard to encode product information in Code 128 barcodes).

gt.nit

NIT (Número de Identificación Tributaria, Guatemala tax number).

hr.oib

OIB (Osobni identifikacijski broj, Croatian identification number).

hu.anum

ANUM (Közösségi adószám, Hungarian VAT number).

iban

IBAN (International Bank Account Number).

id.npwp

NPWP (Nomor Pokok Wajib Pajak, Indonesian VAT Number).

ie.pps

PPS No (Personal Public Service Number, Irish personal number).

ie.vat

VAT (Irish tax reference number).

il.hp

Company Number (מספר חברה, or short ח.פ.

il.idnr

Identity Number (Mispar Zehut, מספר זהות, Israeli identity number).

imei

IMEI (International Mobile Equipment Identity).

imo

IMO number (International Maritime Organization number).

imsi

IMSI (International Mobile Subscriber Identity).

in_.aadhaar

Aadhaar (Indian personal identity number).

in_.epic

EPIC (Electoral Photo Identity Card, Indian Voter ID).

in_.gstin

GSTIN (Goods and Services Tax identification number, Indian VAT number).

in_.pan

PAN (Permanent Account Number, Indian income tax identifier).

in_.vid

VID (Indian personal virtual identity number).

is_.kennitala

Kennitala (Icelandic personal and organisation identity code).

is_.vsk

VSK number (Virðisaukaskattsnúmer, Icelandic VAT number).

isan

ISAN (International Standard Audiovisual Number).

isbn

ISBN (International Standard Book Number).

isil

ISIL (International Standard Identifier for Libraries).

isin

ISIN (International Securities Identification Number).

ismn

ISMN (International Standard Music Number).

iso11649

ISO 11649 (Structured Creditor Reference).

iso6346

ISO 6346 (International standard for container identification)

isrc

ISRC (International Standard Recording Code).

issn

ISSN (International Standard Serial Number).

it.aic

AIC (Italian code for identification of drugs).

it.codicefiscale

Codice Fiscale (Italian tax code for individuals).

it.iva

Partita IVA (Italian VAT number).

jp.cn

CN (法人番号, hōjin bangō, Japanese Corporate Number).

ke.pin

PIN (Personal Identification Number, Kenya tax number).

kr.brn

BRN (사업자 등록 번호, South Korea Business Registration Number).

kr.rrn

RRN (South Korean resident registration number).

lei

LEI (Legal Entity Identifier).

li.peid

PEID (Liechtenstein tax code for individuals and entities).

lt.asmens

Asmens kodas (Lithuanian, personal numbers).

lt.pvm

PVM (Pridėtinės vertės mokestis mokėtojo kodas, Lithuanian VAT number).

lu.tva

TVA (taxe sur la valeur ajoutée, Luxembourgian VAT number).

lv.pvn

PVN (Pievienotās vērtības nodokļa, Latvian VAT number).

ma.ice

ICE (Identifiant Commun de l’Entreprise, التعريف الموحد للمقاولة, Morocco tax number).

mac

MAC address (Media Access Control address).

mc.tva

n° TVA (taxe sur la valeur ajoutée, Monacan VAT number).

md.idno

IDNO (Moldavian company identification number).

me.iban

Montenegro IBAN (International Bank Account Number).

me.pib

PIB (Poreski Identifikacioni Broj, Montenegro tax number).

meid

MEID (Mobile Equipment Identifier).

mk.edb

ЕДБ (Едниствен Даночен Број, North Macedonia tax number).

mt.vat

VAT (Maltese VAT number).

mu.nid

ID number (Mauritian national identifier).

mx.curp

CURP (Clave Única de Registro de Población, Mexican personal ID).

mx.rfc

RFC (Registro Federal de Contribuyentes, Mexican tax number).

my.nric

NRIC No.

nl.brin

BRIN number (the Dutch school identification number).

nl.bsn

BSN (Burgerservicenummer, the Dutch citizen identification number).

nl.btw

Btw-identificatienummer (Omzetbelastingnummer, the Dutch VAT number).

nl.onderwijsnummer

Onderwijsnummer (the Dutch student identification number).

nl.postcode

Postcode (the Dutch postal code).

no.fodselsnummer

Fødselsnummer (Norwegian birth number, the national identity number).

no.iban

Norwegian IBAN (International Bank Account Number).

no.kontonr

Konto nr.

no.mva

MVA (Merverdiavgift, Norwegian VAT number).

no.orgnr

Orgnr (Organisasjonsnummer, Norwegian organisation number).

nz.bankaccount

New Zealand bank account number

nz.ird

IRD number (New Zealand Inland Revenue Department (Te Tari Tāke) number).

pe.cui

CUI (Cédula Única de Identidad, Peruvian identity number).

pe.ruc

RUC (Registro Único de Contribuyentes, Peruvian company tax number).

pk.cnic

CNIC number (Pakistani Computerised National Identity Card number).

pl.nip

NIP (Numer Identyfikacji Podatkowej, Polish VAT number).

pl.pesel

PESEL (Polish national identification number).

pl.regon

REGON (Rejestr Gospodarki Narodowej, Polish register of economic units).

pt.cc

CC (Número de Cartão de Cidadão, Portuguese Identity number).

pt.nif

NIF (Número de identificação fiscal, Portuguese VAT number).

py.ruc

RUC number (Registro Único de Contribuyentes, Paraguay tax number).

ro.cf

CF (Cod de înregistrare în scopuri de TVA, Romanian VAT number).

ro.cnp

CNP (Cod Numeric Personal, Romanian Numerical Personal Code).

ro.cui

CUI or CIF (Codul Unic de Înregistrare, Romanian company identifier).

ro.onrc

ONRC (Ordine din Registrul Comerţului, Romanian Trade Register identifier).

rs.pib

PIB (Poreski Identifikacioni Broj, Serbian tax identification number).

ru.inn

ИНН (Идентификационный номер налогоплательщика, Russian tax identifier).

se.orgnr

Orgnr (Organisationsnummer, Swedish company number).

se.personnummer

Personnummer (Swedish personal identity number).

se.postnummer

Postcode (the Swedish postal code).

se.vat

VAT (Moms, Mervärdesskatt, Swedish VAT number).

sg.uen

UEN (Singapore's Unique Entity Number).

si.ddv

ID za DDV (Davčna številka, Slovenian VAT number).

si.emso

Enotna matična številka občana (Unique Master Citizen Number).

si.maticna

Matična številka poslovnega registra (Corporate Registration Number)

sk.dph

IČ DPH (IČ pre daň z pridanej hodnoty, Slovak VAT number).

sk.rc

RČ (Rodné číslo, the Slovak birth number).

sm.coe

COE (Codice operatore economico, San Marino national tax number).

sv.nit

NIT (Número de Identificación Tributaria, El Salvador tax number).

th.moa

MOA (Thailand Memorandum of Association Number).

th.pin

PIN (Thailand Personal Identification Number).

th.tin

TIN (Thailand Taxpayer Identification Number).

tn.mf

MF (Matricule Fiscal, Tunisia tax number).

tr.tckimlik

T.C.

tr.vkn

VKN (Vergi Kimlik Numarası, Turkish tax identification number).

tw.ubn

UBN (Unified Business Number, 統一編號, Taiwanese tax number).

ua.edrpou

ЄДРПОУ, EDRPOU (Identifier for enterprises and organizations in Ukraine).

ua.rntrc

РНОКПП, RNTRC (Individual taxpayer registration number in Ukraine).

us.atin

ATIN (U.S.

us.ein

EIN (U.S.

us.itin

ITIN (U.S.

us.ptin

PTIN (U.S.

us.rtn

RTN (Routing transport number).

us.ssn

SSN (U.S.

us.tin

TIN (U.S.

uy.rut

RUT (Registro Único Tributario, Uruguay tax number).

vatin

VATIN (International value added tax identification number)

ve.rif

RIF (Registro de Identificación Fiscal, Venezuelan VAT number).

vn.mst

MST (Mã số thuế, Vietnam tax number).

za.idnr

ID number (South African Identity Document number).

za.tin

TIN (South African Tax Identification Number).

Changes in python-stdnum

Contributing to python-stdnum