idnumbers

Welcome to the idnumbers project! Our goal is to provide a python3 library for verifying and parsing national ID numbers. This library can be used to quickly and easily validate and extract information from ID numbers issued by various countries. It is an open source project, so feel free to use and contribute to it.

Features

The idnumbers library offers the following features:

• Verification of national ID numbers: This feature allows you to check if a given ID number is valid and has been issued by the respective country.
• Parsing of national ID numbers: This feature allows you to extract useful information from an ID number such as the date of birth, gender, and more.
• Support for multiple countries: The library currently supports several countries, with more being added in the future.
• Easy to use and well-documented API: The library has a simple and intuitive API that makes it easy to use and well-documented for developers to understand.
• Lightweight and efficient: The library is lightweight, meaning it does not have many dependencies, and it is efficient, meaning it does not consume much memory or processing power.

Installation

Installing idnumbers is easy! You can use pip, the package installer for Python, to install the latest version of the library. Simply open a terminal and run the following command:

It is highly recommended to install the library in a virtual environment, this will prevent conflicts with other python packages in your system. You can create a virtual environment using virtualenv or conda.

For virtualenv:

virtualenv <envname>
source <envname>/bin/activate

For Anaconda:

conda create --name <envname>
conda activate <envname>

Once you have activated your virtual environment, you can install idnumbers by running the following command:

pip install idnumbers

This will install the latest version of idnumbers and its dependencies.

You can also install a specific version of idnumbers by specifying the version number in the command, like this:

pip install idnumbers==<version>

See the changelog for the changes in each release.

Alternatively, you can install from source by cloning the git repository and installing it via

git clone https://github.com/Identique/idnumbers.git
cd idnumbers
pip install .

Please make sure you have the latest version of pip and setuptools installed before proceeding with the installation.

Once you have finished using the library, you can deactivate the virtual environment by running:

deactivate

or

conda deactivate

Usage

Verify National IDs

The idnumbers library makes it easy to verify national ID numbers. Here are some examples of how to use the library for verifying ID numbers.

from idnumbers.nationalid import AUS, NGA, ZAF

# Verify AUS tax file number (with checksum code)
taxfile_number = '32547689'
is_valid = AUS.TaxFileNumber.validate(taxfile_number)
if is_valid:
    print(f'{taxfile_number} is a valid AUS Tax File Number')
else:
    print(f'{taxfile_number} is an invalid AUS Tax File Number')

# Verify AUS driver license number
driver_license = '12 345 678'
is_valid = AUS.DriverLicenseNumber.validate(driver_license)
if is_valid:
    print(f'{driver_license} is a valid AUS Driver License Number')
else:
    print(f'{driver_license} is an invalid AUS Driver License Number')

# Verify AUS Medicare number (with checksum code)
medicare_number = '2123 45670 1'
is_valid = AUS.MedicareNumber.validate(medicare_number)
if is_valid:
    print(f'{medicare_number} is a valid AUS Medicare Number')
else:
    print(f'{medicare_number} is an invalid AUS Medicare Number')

# Verify NGA national id number
nga_nationalid = '12345678901'
is_valid = NGA.NationalID.validate(nga_nationalid)
if is_valid:
    print(f'{nga_nationalid} is a valid Nigerian National ID Number')
else:
    print(f'{nga_nationalid} is an invalid Nigerian National ID Number')

# Verify ZAF nation id number
zaf_nationalid = '7605300675088'
is_valid = ZAF.NationalID.validate(zaf_nationalid)
if is_valid:
    print(f'{zaf_nationalid} is a valid South African ID Number')
else:
    print(f'{zaf_nationalid} is an invalid South African ID Number')

These examples show how to use the idnumbers library to verify different types of national ID numbers for different countries. The validate method returns a boolean value indicating if the ID number is valid or not. All modules under nationalid package support the validate function.

You can also use the library to validate different types of ID numbers for different countries.

It is important to keep in mind that the library is only able to validate the format and the checksum of the ID number, not if it is an actual issued ID number.

Input handling

• validate() returns a bool for any input and is not meant to raise. Anything that is not a str (None, numbers, bytes, lists, ...) gives False, an integer is never converted to a string, so validate(37605030299) is False.
• The whole string must match the ID format. Nothing is stripped, so surrounding whitespace or a trailing newline gives False (the Irish PPS number is the one exception: its own format allows one trailing space).
• Only ASCII digits 0-9 are accepted, other Unicode digits such as ١٢٣ or １２３ give False.
• Separators and letter case are type specific. Several ID types accept their usual written form (for example spaces, dashes or dots inside the number, as in 8924 7352 8038), and a few accept lower case letters. Most types are case sensitive. The METADATA.regexp of each type shows the accepted written form. A few types (for example the Czech TaxNumber, which drops every / anywhere in the input before matching) also normalize the input before checking it, so for those the regexp alone does not show everything they accept.
• parse() returns None for invalid input.

Parse National IDs

The idnumbers library supports the parse function for certain national ID numbers, which allows you to easily extract detailed information from the ID number. The parse function is only available for national IDs for which the METADATA.parsable field is set to True.

For example, the South African ID Number, Nigerian National ID Number and Australian Medicare Number all support the parse function. By using the parse method, you can extract information such as the date of birth, gender, and citizenship from these ID numbers.

Here is an example of how to use the parse function for a South African ID number:

from idnumbers.nationalid import ZAF

# Parse the national ID number
id_number = '7605300675088'
id_data = ZAF.NationalID.parse(id_number)

# Access the date of birth
print(f'Date of birth: {id_data["yyyymmdd"]}')

# Access the gender
print(f'Gender: {id_data["gender"]}')

# Access the citizenship
print(f'Citizenship: {id_data["citizenship"]}')

This example shows how to use the parse method of the ZAF.NationalID class to extract the date of birth, gender and citizenship from a South African ID number. The parse method returns a dictionary with various fields, including yyyymmdd for date of birth, gender for gender and citizenship for citizenship.

Similarly, you can parse the Nigerian National ID Number and Australian Medicare Number by using the NGA.NationalID.parse() and AUS.MedicareNumber.parse() respectively.

Please note that the returned parsed data may vary depending on the country and id type you are using. Also, it is important to keep in mind that the library is only able to validate the format and the checksum of the ID number, not if it is an actual issued ID number.

Supported Countries

Here's the list of the countries we have implemented Country List

Metadata Structure of each ID

Here's the metadata definitions and how to use it in idnumbers: METADATA

Contribution

The idnumbers project is an open-source project and contributions from the community are always welcome. There are several ways you can contribute to the project:

1. Use the library: The best way to contribute to the project is by using the library and providing feedback. This will help us understand how the library is being used and identify areas for improvement.
2. Raise feature requests: If you have an idea for a new feature or an improvement, please raise an issue on GitHub. This will allow us to discuss the feature and plan its implementation.
3. Implement new ID number parsers or validators: The library currently supports several countries, but there is always room for more. If you want to add support for a new country, you can submit a pull request with the implementation. Before that, please raise a new ID number reqeust to us.
4. Report bugs: If you find a bug in the library, please raise an issue on GitHub with a detailed description of the problem.
5. Improve documentation: The library has a well-documented API, but there is always room for improvement. If you find any errors or inconsistencies in the documentation, you can submit a pull request with the changes.

We appreciate any contributions, big or small, and we are always looking for ways to improve the library. If you have any questions or need help getting started, please feel free to reach out to us.

License

The idnumbers project is released in MIT license.

Thank You!

The idnumbers project provides a python3 library for verifying and parsing national ID numbers. It supports multiple countries and provides a simple and well-documented API. The library is open-source, and contributions from the community are always welcome. Whether you're using the library and providing feedback, raising feature requests, implementing new ID number parsers or validators or reporting bugs, you're helping the project to be better.

Thank you for considering using idnumbers in your project. We hope it will be useful for you and we are looking forward to your feedback and contributions