Support for Global Trade Item Number (GTIN).

The biip.gtin module contains Biip’s support for parsing GTIN formats.

A GTIN is a number that uniquely identifies a trade item.

This class can interpet the following GTIN formats:

  • GTIN-8, found in EAN-8 barcodes.

  • GTIN-12, found in UPC-A and UPC-E barcodes.

  • GTIN-13, found in EAN-13 barcodes.

  • GTIN-14, found in ITF-14 barcodes, as well as a data field in GS1 barcodes.

If you only want to parse GTINs, you can import the GTIN parser directly instead of using biip.parse().

>>> from biip.gtin import Gtin

If parsing succeeds, it returns a Gtin object.

>>> gtin = Gtin.parse("5901234123457")
>>> gtin
Gtin(value='5901234123457', format=GtinFormat.GTIN_13,
prefix=GS1Prefix(value='590', usage='GS1 Poland'),
payload='590123412345', check_digit=7, packaging_level=None)

A GTIN can be converted to any other GTIN format, as long as the target format is longer.

>>> gtin.as_gtin_14()

As all GTINs can be converted to GTIN-14, it is the recommended format to use when storing or comparing GTINs. For example, when looking up a product associated with a GTIN, the GTIN should first be expanded to a GTIN-14 before using it to query the product catalog.

class biip.gtin.Gtin(value, format, prefix, payload, check_digit, packaging_level=None)

Data class containing a GTIN.

value: str

Raw unprocessed value.

May include leading zeros.

format: biip.gtin._enums.GtinFormat

GTIN format, either GTIN-8, GTIN-12, GTIN-13, or GTIN-14.

Classification is done after stripping leading zeros.

prefix: Optional[biip.gs1._prefixes.GS1Prefix]

The GS1 prefix, indicating what GS1 country organization that assigned code range.

payload: str

The actual payload, including packaging level if any, company prefix, and item reference. Excludes the check digit.

check_digit: int

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

packaging_level: Optional[int] = None

Packaging level is the first digit in GTIN-14 codes.

This digit is used for wholesale shipments, e.g. the GTIN-14 product identifier in GS1-128 barcodes, but not in the GTIN-13 barcodes used for retail products.

classmethod parse(value, *, rcn_region=None)

Parse the given value into a Gtin object.

Both GTIN-8, GTIN-12, GTIN-13, and GTIN-14 are supported.

  • value (str) – The value to parse.

  • rcn_region (Optional[RcnRegion]) – The geographical region whose rules should be used to interpret Restricted Circulation Numbers (RCN). Needed to extract e.g. variable weight/price from GTIN.

Return type



GTIN data structure with the successfully extracted data. The checksum is guaranteed to be valid if a GTIN object is returned.


ParseError – If the parsing fails.


Format as a GTIN-8.

Return type



Format as a GTIN-12.

Return type



Format as a GTIN-13.

Return type



Format as a GTIN-14.

Return type



Create a new GTIN where the variable measure is zeroed out.

This method is a no-op for proper GTINs. For RCNs, see the method on the Rcn subclass.

Return type



A GTIN instance with zeros in the variable measure places.


EncodeError – If the rules for variable measures in the region are unknown.

class biip.gtin.GtinFormat(value)

Enum of GTIN formats.

GTIN_8 = 8


GTIN_12 = 12


GTIN_13 = 13


GTIN_14 = 14


property length: int

Length of a GTIN of the given format.

Return type


class biip.gtin.Rcn(value, format, prefix, payload, check_digit, packaging_level=None)

Restricted Circulation Number (RCN) is a subset of GTIN.

Both RCN-8, RCN-12, and RCN-13 are supported. There is no 14 digit version of RCN.

RCN-12 with prefix 2 and RCN-13 with prefix 02 or 20-29 have the same semantics across a geographic region, defined by the local GS1 Member Organization.

RCN-8 with prefix 0 or 2, RCN-12 with prefix 4, and RCN-13 with prefix 04 or 40-49 have semantics that are only defined within a single company.

Use biip.gtin.Gtin.parse() to parse potential RCNs. This subclass is returned if the GS1 Prefix signifies that the value is an RCN.


GS1 General Specifications, section 2.1.11-2.1.12

usage: Optional[RcnUsage] = None

Where the RCN can be circulated, in a geographical region or within a company.

region: Optional[RcnRegion] = None

The geographical region whose rules are used to interpret the contents of the RCN.

weight: Optional[Decimal] = None

A variable weight value extracted from the GTIN.

count: Optional[int] = None

A variable count extracted from the GTIN.

price: Optional[Decimal] = None

A variable weight price extracted from the GTIN.

money: Optional['moneyed.Money'] = None

A Money value created from the variable weight price. Only set if py-moneyed is installed and the currency is known.


Create a new RCN where the variable measure is zeroed out.

This provides us with a number which still includes the item reference, but does not vary with weight/price, and can thus be used to lookup the relevant trade item in a database or similar.

This has no effect on RCNs intended for use within a company, as the semantics of those numbers vary from company to company.

Return type



A RCN instance with zeros in the variable measure places.


EncodeError – If the rules for variable measures in the region are unknown.

class biip.gtin.RcnUsage(value)

Enum of RCN usage restrictions.


Usage of RCN restricted to geopgraphical area.

COMPANY = 'company'

Usage of RCN restricted to internally in a company.

class biip.gtin.RcnRegion(value)

Enum of geographical regions with custom RCN rules.

The value of the enum is the lowercase ISO 3166-1 Alpha-2 code.

DENMARK = 'dk'


ESTONIA = 'ee'


FINLAND = 'fi'


GERMANY = 'de'



Great Britain

LATVIA = 'lv'




NORWAY = 'no'


SWEDEN = 'se'


classmethod from_iso_3166_1_numeric_code(code)

Get the region from an ISO 3166-1 numeric code.


code (Union[int, str]) – The ISO 3166-1 numeric code.

Return type



The RCN region or None if the code does not match a RCN region known to Biip.


ValueError – If the code is not a valid ISO 3166-1 numeric code.


This method was deprecated in Biip 2.2. It will be removed in Biip 3.0.


Get the ISO-4217 currency code for the region.

Return type