Record Locator

What is it?

A record locator provides human-readable alphanumeric representations of numeric IDs (i.e. database primary keys). A good example is the Passenger name record (aka Confirmation code, aka Booking code, etc.) used by airlines.

Some characters are not used in record locators to avoid confusion with others:

Character	similar characters
B	8 (eight)
S	5 (five)
Q	letter "O"
0 (zero)	letter "O"
1 (one)	letter "I"

Both columns have been removed from the character set. This leaves the following characters for code generation:

234679ACDEFGHJKLMNPRTUVWXYZ

So basically this makes it a Base27 encoding.

Examples

Standard (Base29) record locator:

• Integer 100 encodes to 6R

• Integer 20290290 encodes to 3G7W3A

Usage

Default record locator

from record_locator.record_locator import RecordLocator


rl = RecordLocator()
encoded_id = rl.encode(100)
decoded_id = rl.decode("6R")

print (encoded_id)
print (decoded_id)

Custom record locator

Just construct the RecordLocator with base_characters set containing all characters needed.

Below an example generating ids only containing the following characters: ABCDEFGHIJKL

from record_locator.record_locator import RecordLocator


rl = RecordLocator(base_characters="ABCDEFGHIJKL")
encoded_id = rl.encode(100)
decoded_id = rl.decode("IE")

print (encoded_id)
print (decoded_id)

Record locator with checksum

from record_locator.record_locator import RecordLocator


rl = RecordLocator(has_check_digit=True)
encoded_id = rl.encode(100)
decoded_id = rl.decode("6RK")

print (encoded_id)
print (decoded_id)

The checksum is generated using the length of the character set and the generated record string. Each character in the generated string is transformed into its integer representation (zero-based index position in character set) and multiplied by its position (non zero-based index) in the ID string. All this values are added to a checksum.

Checksum for 6R = 3 * 1 + 19 * 2 = 41

• 6 is the 4th character (index = 3) in the default set

• R is the 20th character (index = 19) in the default set

The final step is to run a modulo operation on the checksum to assign a character from the character set:

Checksum for 6R = 41 % 27 = 14

Looking up index 14 in the character set gives: K

The record locator string including a check digit for the value 100 is: 6RK

Tests

Unit tests can be found in record_locator/test_record_locator.py