Container Code Validation in Python — ISO 6346 Explained

1. What is ISO 6346?

ISO 6346 is an international standard that defines the coding, identification, and marking of shipping containers used in intermodal freight transport. Published by the International Organization for Standardization, it assigns each container a globally unique 11-character code consisting of letters and digits.

The standard is maintained by the Bureau International des Containers (BIC), which operates the global registry of owner codes. Every container manufacturer, leasing company, and shipping line must register its owner code with BIC before putting containers into service.

In logistics software, container codes appear in bills of lading, customs declarations, terminal operating systems, and vessel manifests. A single transposition error can route a container to the wrong yard, delay customs clearance, or generate phantom inventory.

2. Anatomy of a container code

An ISO 6346 container code has exactly 11 characters, split into four parts:

3. The mod-11 check digit algorithm

ISO 6346 uses a weighted mod-11 algorithm. Each of the first 10 characters is assigned a numeric value, multiplied by a power-of-2 weight, and the sum modulo 11 produces the check digit. If the result is 10, it is mapped to 0.

Let's walk through CSQU3054383:

# container_check_digit.py — ISO 6346 mod-11 check digit
import re


def validate_container_code(code: str) -> bool:
    code = code.upper().replace(" ", "").replace("-", "")
    if not re.match(r"^[A-Z]{3}[UJZR]\d{7}$", code):
        return False

    def char_value(ch: str) -> int:
        if ch.isdigit():
            return int(ch)
        n = ord(ch) - ord("A")
        # value = 10 + n + number of multiples of 11 up to (10 + n)
        return 10 + n + (10 + n) // 11

    total = sum(
        char_value(code[i]) * (2 ** i) for i in range(10)
    )

    check_digit = total % 11 % 10  # if mod-11 gives 10, map to 0
    return check_digit == int(code[10])


print(validate_container_code("CSQU3054383"))  # True  ✓
print(validate_container_code("CSQU3054384"))  # False ✗ wrong check digit
print(validate_container_code("MAEU1234567"))  # checks dynamically

4. Category codes — U, J, Z, R

The fourth character of a container code identifies the type of equipment. ISO 6346 defines four category identifiers:

5. Why container code validation matters

6. The production-ready solution

The IsValid Container Code API validates the format, computes the ISO 6346 mod-11 check digit, and returns the parsed components — owner code, category, serial number, and check digit — in a single call.

Full parameter reference and response schema: Container Code Validation API docs →

7. Python code example

Using the isvalid-sdk package or the requests library. Install with pip install isvalid-sdk or pip install requests.

# container_validator.py
import os
from isvalid_sdk import IsValidConfig, create_client

iv = create_client(IsValidConfig(api_key=os.environ["ISVALID_API_KEY"]))

result = iv.container_code("CSQU3054383")

if not result["valid"]:
    print("Invalid container code")
else:
    print(f"Owner code: {result['ownerCode']}")       # → 'CSQ'
    print(f"Category: {result['categoryName']}")       # → 'Freight container'
    print(f"Serial: {result['serialNumber']}")         # → '305438'
    print(f"Check digit: {result['checkDigit']}")      # → '3'

# Validate container codes in a vessel manifest
def process_manifest(containers: list[dict]) -> list[dict]:
    results = []

    for entry in containers:
        if not entry.get("container_code"):
            results.append({**entry, "status": "missing"})
            continue

        check = validate_container_code(entry["container_code"])

        if not check["valid"]:
            results.append({**entry, "status": "invalid"})
            continue

        results.append({
            **entry,
            "container_code": entry["container_code"].upper().replace(" ", "").replace("-", ""),
            "owner_code": check["ownerCode"],
            "category": check["categoryName"],
            "serial_number": check["serialNumber"],
            "status": "valid",
        })

    return results

8. cURL example

Validate a standard freight container:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.isvalid.dev/v0/container-code?value=CSQU3054383"

Validate a container with an invalid check digit:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.isvalid.dev/v0/container-code?value=CSQU3054380"

Validate a reefer container:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.isvalid.dev/v0/container-code?value=TRIU4567890"

9. Understanding the response

Valid container code:

{
  "valid": true,
  "ownerCode": "CSQ",
  "categoryCode": "U",
  "categoryName": "Freight container",
  "serialNumber": "305438",
  "checkDigit": "3"
}

Invalid container code:

{
  "valid": false
}

10. Edge cases — tanks, reefers, and more

# The critical line in the check digit calculation:
check_digit = total % 11 % 10  # double-mod handles 10 → 0