Skip to content

biip.gln

Global Location Number (GLN).

GLNs are used to identify physical locations, digital locations, legal entities, and organizational functions.

If you only want to parse GLNs, you can import the GLN parser directly.

>>> from biip.gln import Gln

If parsing succeeds, it returns a Gln object.

>>> gln = Gln.parse("1234567890128")
>>> pprint(gln)
Gln(
    value='1234567890128',
    prefix=GS1Prefix(
        value='123',
        usage='GS1 US'
    ),
    company_prefix=GS1CompanyPrefix(
        value='1234567890'
    ),
    payload='123456789012',
    check_digit=8
)

As GLNs do not appear independently in barcodes, the GLN parser is not a part of the top-level parser biip.parse(). However, if you are parsing a barcode with GS1 element strings including a GLN, the GLN will be parsed and validated using the Gln class.

>>> import biip
>>> gln = (
...     biip.parse("4101234567890128")
...     .gs1_message
...     .element_strings.get(data_title="SHIP TO")
...     .gln
... )
>>> pprint(gln)
Gln(
    value='1234567890128',
    prefix=GS1Prefix(
        value='123',
        usage='GS1 US'
    ),
    company_prefix=GS1CompanyPrefix(
        value='1234567890'
    ),
    payload='123456789012',
    check_digit=8
)

Gln dataclass

Dataclass containing a GLN.

Source code in src/biip/gln.py 
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
@dataclass(frozen=True)
class Gln:
    """Dataclass containing a GLN."""

    value: str
    """Raw unprocessed value."""

    prefix: GS1Prefix | None
    """The [GS1 Prefix][biip.gs1_prefixes.GS1Prefix].

    Indicating what GS1 country organization that assigned code range.
    """

    company_prefix: GS1CompanyPrefix | None
    """The [GS1 Company Prefix][biip.gs1_prefixes.GS1CompanyPrefix].

    Identifying the company that issued the GLN.
    """

    payload: str
    """The actual payload.

    Including extension digit, company prefix, and item reference. Excludes the
    check digit.
    """

    check_digit: int
    """Check digit used to check if the GLN as a whole is valid."""

    @classmethod
    def parse(
        cls,
        value: str,
        *,
        config: ParseConfig | None = None,  # noqa: ARG003
    ) -> Gln:
        """Parse the given value into a [`Gln`][biip.gln.Gln] object.

        The checksum is guaranteed to be valid if a GLN object is returned.

        Args:
            value: The value to parse.
            config: Configuration options for parsing.

        Returns:
            GLN data structure with the successfully extracted data.

        Raises:
            ParseError: If the parsing fails.
        """
        value = value.strip()

        if len(value) != 13:
            msg = (
                f"Failed to parse {value!r} as GLN: "
                f"Expected 13 digits, got {len(value)}."
            )
            raise ParseError(msg)

        if not value.isdecimal():
            msg = f"Failed to parse {value!r} as GLN: Expected a numerical value."
            raise ParseError(msg)

        prefix = GS1Prefix.extract(value)
        company_prefix = GS1CompanyPrefix.extract(value)
        payload = value[:-1]
        check_digit = int(value[-1])

        calculated_check_digit = gs1_standard_check_digit(payload)
        if check_digit != calculated_check_digit:
            msg = (
                f"Invalid GLN check digit for {value!r}: "
                f"Expected {calculated_check_digit!r}, got {check_digit!r}."
            )
            raise ParseError(msg)

        return cls(
            value=value,
            prefix=prefix,
            company_prefix=company_prefix,
            payload=payload,
            check_digit=check_digit,
        )

    def as_gln(self) -> str:
        """Format as a GLN."""
        return self.value

check_digit instance-attribute 

check_digit: int

Check digit used to check if the GLN as a whole is valid.

company_prefix instance-attribute 

company_prefix: GS1CompanyPrefix | None

The GS1 Company Prefix.

Identifying the company that issued the GLN.

payload instance-attribute 

payload: str

The actual payload.

Including extension digit, company prefix, and item reference. Excludes the check digit.

prefix instance-attribute 

prefix: GS1Prefix | None

The GS1 Prefix.

Indicating what GS1 country organization that assigned code range.

value instance-attribute 

value: str

Raw unprocessed value.

as_gln 

as_gln() -> str

Format as a GLN.

Source code in src/biip/gln.py 
147
148
149
def as_gln(self) -> str:
    """Format as a GLN."""
    return self.value

parse classmethod 

parse(
    value: str, *, config: ParseConfig | None = None
) -> Gln

Parse the given value into a Gln object.

The checksum is guaranteed to be valid if a GLN object is returned.

Parameters:

  • value (str) –

    The value to parse.

  • config (ParseConfig | None, default: None ) –

    Configuration options for parsing.

Returns:

  • Gln –

    GLN data structure with the successfully extracted data.

Raises:

Source code in src/biip/gln.py 
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
@classmethod
def parse(
    cls,
    value: str,
    *,
    config: ParseConfig | None = None,  # noqa: ARG003
) -> Gln:
    """Parse the given value into a [`Gln`][biip.gln.Gln] object.

    The checksum is guaranteed to be valid if a GLN object is returned.

    Args:
        value: The value to parse.
        config: Configuration options for parsing.

    Returns:
        GLN data structure with the successfully extracted data.

    Raises:
        ParseError: If the parsing fails.
    """
    value = value.strip()

    if len(value) != 13:
        msg = (
            f"Failed to parse {value!r} as GLN: "
            f"Expected 13 digits, got {len(value)}."
        )
        raise ParseError(msg)

    if not value.isdecimal():
        msg = f"Failed to parse {value!r} as GLN: Expected a numerical value."
        raise ParseError(msg)

    prefix = GS1Prefix.extract(value)
    company_prefix = GS1CompanyPrefix.extract(value)
    payload = value[:-1]
    check_digit = int(value[-1])

    calculated_check_digit = gs1_standard_check_digit(payload)
    if check_digit != calculated_check_digit:
        msg = (
            f"Invalid GLN check digit for {value!r}: "
            f"Expected {calculated_check_digit!r}, got {check_digit!r}."
        )
        raise ParseError(msg)

    return cls(
        value=value,
        prefix=prefix,
        company_prefix=company_prefix,
        payload=payload,
        check_digit=check_digit,
    )