Metadata-Version: 2.4
Name: barcodefyi
Version: 0.1.1
Summary: Barcode symbology encyclopedia API client — look up UPC, EAN, Code 128, QR, Data Matrix formats, standards, and specifications from BarcodeFYI.
Project-URL: Homepage, https://barcodefyi.com
Project-URL: Symbology Explorer, https://barcodefyi.com/symbology/
Project-URL: Standards Reference, https://barcodefyi.com/standard/
Project-URL: Documentation, https://barcodefyi.com/developers/
Project-URL: Repository, https://github.com/fyipedia/barcodefyi
Project-URL: Issues, https://github.com/fyipedia/barcodefyi/issues
Project-URL: Changelog, https://github.com/fyipedia/barcodefyi/releases
Author: FYIPedia
License-Expression: MIT
License-File: LICENSE
Keywords: api-client,barcode,code-128,data-matrix,ean,gs1,isbn,reference,symbology,upc
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Provides-Extra: all
Requires-Dist: httpx>=0.27; extra == 'all'
Requires-Dist: mcp>=1.0; extra == 'all'
Requires-Dist: rich>=13.0; extra == 'all'
Requires-Dist: typer>=0.15; extra == 'all'
Provides-Extra: api
Requires-Dist: httpx>=0.27; extra == 'api'
Provides-Extra: cli
Requires-Dist: rich>=13.0; extra == 'cli'
Requires-Dist: typer>=0.15; extra == 'cli'
Provides-Extra: mcp
Requires-Dist: mcp>=1.0; extra == 'mcp'
Description-Content-Type: text/markdown

# barcodefyi

[![PyPI version](https://agentgif.com/badge/pypi/barcodefyi/version.svg)](https://pypi.org/project/barcodefyi/)
[![Python](https://img.shields.io/pypi/pyversions/barcodefyi)](https://pypi.org/project/barcodefyi/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)

Barcode symbology encyclopedia API client for Python. Look up 50+ barcode formats across 1D linear, 2D matrix, stacked, and composite categories, 30+ international standards from ISO and GS1, anatomy components, check digit algorithms, and GS1 company prefixes from [BarcodeFYI](https://barcodefyi.com) -- the comprehensive barcode reference with 518 records covering UPC, EAN, Code 128, QR Code, Data Matrix, PDF417, and every major symbology in commercial and industrial use.

Extracted from [BarcodeFYI](https://barcodefyi.com), a barcode symbology platform with 518 records spanning 50+ symbologies, 30+ standards, anatomy breakdowns, and industry-specific encoding guides used by supply chain engineers, retail systems developers, and industrial automation architects worldwide.

> **Explore barcodes at [barcodefyi.com](https://barcodefyi.com)** -- [Symbology Explorer](https://barcodefyi.com/symbology/) | [Standards Reference](https://barcodefyi.com/standard/) | [Anatomy Guide](https://barcodefyi.com/anatomy/) | [GS1 Prefixes](https://barcodefyi.com/prefix/)

<p align="center">
  <img src="https://raw.githubusercontent.com/fyipedia/barcodefyi/main/demo.gif" alt="barcodefyi demo -- barcode symbology lookup, comparison, and standard reference in Python" width="800">
</p>

## Table of Contents

- [Install](#install)
- [Quick Start](#quick-start)
- [What You'll Find on BarcodeFYI](#what-youll-find-on-barcodefyi)
  - [1D Linear Symbologies](#1d-linear-symbologies)
  - [2D Matrix Symbologies](#2d-matrix-symbologies)
  - [Stacked and Composite Symbologies](#stacked-and-composite-symbologies)
  - [GS1 System and Company Prefixes](#gs1-system-and-company-prefixes)
  - [Barcode Anatomy](#barcode-anatomy)
  - [Check Digit Algorithms](#check-digit-algorithms)
  - [Key Barcode Standards](#key-barcode-standards)
- [API Endpoints](#api-endpoints)
- [Command-Line Interface](#command-line-interface)
- [MCP Server (Claude, Cursor, Windsurf)](#mcp-server-claude-cursor-windsurf)
- [REST API Client](#rest-api-client)
- [Learn More About Barcodes](#learn-more-about-barcodes)
- [Also Available](#also-available)
- [Tag FYI Family](#tag-fyi-family)
- [FYIPedia Developer Tools](#fyipedia-developer-tools)
- [License](#license)

## Install

```bash
pip install barcodefyi[api]     # API client (httpx)
pip install barcodefyi[cli]     # + CLI (typer, rich)
pip install barcodefyi[mcp]     # + MCP server
pip install barcodefyi[all]     # Everything
```

## Quick Start

```python
from barcodefyi.api import BarcodeFYI

with BarcodeFYI() as api:
    # Search symbologies, standards, components, glossary
    results = api.search("upc")
    print(results)

    # Look up a specific symbology by slug
    upc = api.symbology("upc-a")
    print(upc["name"], upc["year_introduced"])  # UPC-A 1974

    # Compare two symbologies side-by-side
    diff = api.compare("upc-a", "ean-13")
    print(diff)

    # Discover a random symbology
    surprise = api.random()
    print(surprise["name"])
```

## What You'll Find on BarcodeFYI

BarcodeFYI is a comprehensive barcode symbology encyclopedia covering 50+ formats across 1D linear, 2D matrix, stacked, and composite categories. Barcodes are machine-readable optical labels that encode data using patterns of bars, spaces, dots, or modules -- the foundation of supply chain management, retail checkout, healthcare tracking, and industrial automation worldwide.

### 1D Linear Symbologies

One-dimensional barcodes encode data in a single row of bars and spaces. They remain the dominant format in retail and logistics due to omnidirectional scanning, low print cost, and decades of infrastructure investment. Each symbology defines a specific character set, encoding density, and error detection mechanism.

| Symbology | Year | Characters | Density | Primary Use |
|-----------|------|------------|---------|-------------|
| UPC-A | 1974 | 12 numeric | Low | US/Canada retail checkout |
| UPC-E | 1974 | 8 numeric (compressed) | Low | Small retail items |
| EAN-13 | 1977 | 13 numeric | Low | International retail (GTIN-13) |
| EAN-8 | 1977 | 8 numeric | Low | Small international products |
| Code 128 | 1981 | Full ASCII (128 chars) | High | Shipping labels, GS1-128 |
| Code 39 | 1974 | 43 alphanumeric | Medium | Government, defense (MIL-STD-1189) |
| Code 93 | 1982 | Full ASCII | High | Logistics, postal |
| Interleaved 2 of 5 | 1972 | Numeric pairs | Medium | Warehouse carton marking |
| Codabar | 1972 | 16 characters | Low | Blood banks, FedEx airbills |
| MSI Plessey | 1971 | 10 numeric | Low | Retail shelf marking |

**UPC-A structure**: A 12-digit UPC-A barcode contains a number system digit (0=standard, 2=weighted items, 5=coupons), a 5-digit manufacturer code assigned by GS1 US, a 5-digit product code assigned by the manufacturer, and a Modulo 10 check digit. The barcode encodes these digits using three bar widths across 95 modules, flanked by start (101), center (01010), and stop (101) guard patterns.

**EAN-13 structure**: EAN-13 extends UPC-A with a leading country code digit encoded implicitly through the parity pattern of the left-side digits. GS1 country prefixes range from 000-019 (US/Canada) to 690-699 (China), 450-459 (Japan), and 880 (South Korea). The check digit uses the same Modulo 10 algorithm: alternate digits weighted 1 and 3, subtracted from the next multiple of 10.

Learn more: [Symbology Explorer](https://barcodefyi.com/symbology/) | [Barcode Anatomy](https://barcodefyi.com/anatomy/)

### 2D Matrix Symbologies

Two-dimensional barcodes encode data in both horizontal and vertical dimensions, achieving dramatically higher data density. They use patterns of dark and light modules arranged in a matrix, with built-in error correction that allows reliable reading even when partially damaged or obscured.

| Symbology | Year | Max Capacity | Error Correction | Primary Use |
|-----------|------|-------------|-----------------|-------------|
| QR Code (Model 2) | 1997 | 7,089 numeric | Reed-Solomon (7-30%) | Mobile apps, marketing, payments |
| Data Matrix (ECC 200) | 1994 | 3,116 numeric | Reed-Solomon | Electronics, pharma serialization |
| Aztec Code | 1995 | 3,832 numeric | Reed-Solomon (5-95%) | Boarding passes (BCBP), transit tickets |
| MaxiCode | 1992 | 138 numeric | Reed-Solomon | UPS package sorting |
| PDF417 | 1991 | 2,710 numeric | Reed-Solomon (1-512 cw) | Driver licenses (AAMVA), shipping |
| Han Xin Code | 2007 | 7,827 numeric | Reed-Solomon | Chinese logistics, government |

**Data Matrix** is the dominant symbology for small-item marking in electronics manufacturing and pharmaceutical serialization. Its ECC 200 variant uses Reed-Solomon error correction with adjustable redundancy. The smallest Data Matrix symbol (10x10 modules) encodes 6 numeric or 3 alphanumeric characters, while the largest (144x144) holds 3,116 numeric characters.

Learn more: [Standards Reference](https://barcodefyi.com/standard/) | [Glossary](https://barcodefyi.com/glossary/)

### Stacked and Composite Symbologies

Stacked symbologies arrange multiple 1D barcode rows vertically to increase data density without requiring 2D imager hardware. Composite symbologies combine a 1D linear component with a 2D composite component (CC-A, CC-B, or CC-C) to link primary identification with supplementary data.

| Symbology | Type | Rows | Max Capacity | Standard |
|-----------|------|------|-------------|----------|
| PDF417 | Stacked | 3-90 | 2,710 numeric | ISO 15438 |
| Code 49 | Stacked | 2-8 | 49 alphanumeric | USS Code 49 |
| Codablock F | Stacked | 2-44 | 2,725 alphanumeric | AIM USS |
| GS1 DataBar Composite | Composite | 1D + CC | Varies | ISO 24724 |
| GS1-128 Composite | Composite | 1D + CC | Varies | ISO 24723 |

**GS1 DataBar** (formerly RSS -- Reduced Space Symbology) is designed specifically for point-of-sale scanning of small, difficult-to-mark items. Variants include Omnidirectional, Stacked, Limited, Expanded, and Truncated, each optimizing for different scanning environments and data requirements.

Learn more: [GS1 Prefixes](https://barcodefyi.com/prefix/) | [Industry Applications](https://barcodefyi.com/industry/)

### GS1 System and Company Prefixes

The GS1 system provides the global infrastructure for barcode identification through a hierarchical numbering scheme. GS1 assigns unique company prefixes that serve as the foundation for GTINs (Global Trade Item Numbers), SSCCs (Serial Shipping Container Codes), and GLNs (Global Location Numbers).

| GS1 Prefix Range | Assignment | Coverage |
|-------------------|-----------|----------|
| 000-019 | GS1 US | United States and Canada |
| 020-029 | Restricted distribution | In-store use only |
| 030-039 | GS1 US (drugs) | US pharmaceutical NDC/HRI |
| 300-379 | GS1 France | France and overseas territories |
| 400-440 | GS1 Germany | Germany |
| 450-459 | GS1 Japan | Japan (also 490-499) |
| 690-699 | GS1 China | China |
| 880 | GS1 South Korea | South Korea |
| 978-979 | ISBN/ISMN | Books and sheet music |

A GS1 Company Prefix (GCP) typically ranges from 7 to 11 digits. Longer prefixes allow fewer unique product codes per company but cost less to license. For example, a 7-digit GCP allows up to 100,000 unique GTINs, while an 11-digit GCP allows only 10.

Learn more: [GS1 Prefixes](https://barcodefyi.com/prefix/) | [Glossary](https://barcodefyi.com/glossary/)

### Barcode Anatomy

Every barcode consists of fundamental structural components that enable reliable machine reading. Understanding these components is essential for print quality optimization, scanner configuration, and troubleshooting read failures.

| Component | Function | Critical For |
|-----------|----------|-------------|
| Quiet Zone | Mandatory whitespace margin (10x module for 1D) | Scanner must distinguish barcode from background |
| Start/Stop Characters | Format identification patterns | Scanner identifies symbology type |
| Data Characters | Encoded payload (bars/spaces/modules) | Actual data content |
| Check Digit | Error detection (Modulo 10, Modulo 43, etc.) | Data integrity verification |
| Finder Patterns | Orientation detection (2D only) | Camera-based scanning alignment |
| Timing Patterns | Module grid coordinate mapping (2D only) | Accurate module sampling |
| Error Correction | Reed-Solomon codewords (2D only) | Damage recovery |

Learn more: [Anatomy Explorer](https://barcodefyi.com/anatomy/) | [Check Digit Algorithms](https://barcodefyi.com/check-digit/)

### Check Digit Algorithms

Barcode check digits detect transcription errors, substitution errors, and adjacent transposition errors. Different symbologies use different algorithms:

| Algorithm | Used By | Detection Capability |
|-----------|---------|---------------------|
| Modulo 10 (Luhn variant) | UPC-A, EAN-13, ITF-14 | Single-digit errors, most transpositions |
| Modulo 43 | Code 39 | Single substitution errors |
| Modulo 103 | Code 128 | Single-digit and double-digit errors |
| Modulo 47 | Code 93 | Two check characters for higher reliability |
| Reed-Solomon | QR Code, Data Matrix, PDF417 | Burst errors, up to 30% damage recovery |

### Key Barcode Standards

| Standard | Organization | Scope |
|----------|-------------|-------|
| ISO/IEC 15420 | ISO | EAN/UPC symbology specification |
| ISO/IEC 15417 | ISO | Code 128 and GS1-128 |
| ISO/IEC 16022 | ISO | Data Matrix symbology |
| ISO/IEC 18004 | ISO | QR Code specification |
| ISO/IEC 15438 | ISO | PDF417 symbology |
| ISO/IEC 24778 | ISO | Aztec Code specification |
| ISO/IEC 24724 | ISO | GS1 DataBar symbology |
| GS1 General Specifications | GS1 | Global supply chain standards |
| AIM DPM | AIM | Direct Part Marking quality standard |

Learn more: [Standards Reference](https://barcodefyi.com/standard/) | [Industry Applications](https://barcodefyi.com/industry/)

## API Endpoints

Free, no authentication required. JSON responses with CORS enabled.

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/api/symbology/{slug}/` | Barcode symbology detail with specs |
| GET | `/api/family/{slug}/` | Symbology family with evolution story |
| GET | `/api/standard/{slug}/` | Standard detail with linked symbologies |
| GET | `/api/component/{slug}/` | Anatomy component detail |
| GET | `/api/term/{slug}/` | Glossary term definition |
| GET | `/api/search/?q={query}` | Search across all content types |
| GET | `/api/compare/?a={slug}&b={slug}` | Compare two symbologies |
| GET | `/api/random/` | Random symbology discovery |
| GET | `/api/industry/{slug}/` | Industry barcode usage |
| GET | `/api/openapi.json` | OpenAPI 3.1.0 specification |

### Example

```bash
# Search for UPC barcode formats
curl -s "https://barcodefyi.com/api/search/?q=upc" | python -m json.tool
```

```json
{
  "results": [
    {
      "slug": "upc-a",
      "name": "UPC-A",
      "type": "symbology",
      "description": "Universal Product Code, 12-digit numeric barcode..."
    }
  ]
}
```

Full API documentation at [barcodefyi.com/api/](https://barcodefyi.com/api/).
OpenAPI 3.1.0 spec: [barcodefyi.com/api/openapi.json](https://barcodefyi.com/api/openapi.json).

## Command-Line Interface

```bash
barcodefyi search "code 128"          # Search all content
barcodefyi symbology upc-a            # Symbology detail
barcodefyi compare upc-a ean-13       # Side-by-side comparison
barcodefyi random                     # Discover a random symbology
```

## MCP Server (Claude, Cursor, Windsurf)

```json
{
    "mcpServers": {
        "barcodefyi": {
            "command": "uvx",
            "args": ["--from", "barcodefyi[mcp]", "python", "-m", "barcodefyi.mcp_server"]
        }
    }
}
```

Tools: `barcode_search`, `barcode_lookup`, `barcode_compare`

## REST API Client

```python
from barcodefyi.api import BarcodeFYI

with BarcodeFYI() as api:
    # All 10 endpoints available
    api.search("upc")                      # Full-text search
    api.symbology("upc-a")                 # Symbology detail
    api.family("1d-linear")                # Symbology family
    api.standard("iso-iec-15420")          # Standard detail
    api.component("quiet-zone")            # Anatomy component
    api.glossary_term("symbology")         # Glossary term
    api.compare("upc-a", "ean-13")         # Compare two symbologies
    api.random()                           # Random discovery
    api.industry("retail")                 # Industry application
    api.openapi()                          # OpenAPI 3.1.0 spec
```

## Learn More About Barcodes

- **Browse**: [Symbology Explorer](https://barcodefyi.com/symbology/) · [Standards Reference](https://barcodefyi.com/standard/) · [Industry Applications](https://barcodefyi.com/industry/)
- **Reference**: [Anatomy Guide](https://barcodefyi.com/anatomy/) · [GS1 Prefixes](https://barcodefyi.com/prefix/) · [Glossary](https://barcodefyi.com/glossary/)
- **API**: [REST API Docs](https://barcodefyi.com/api/) · [OpenAPI Spec](https://barcodefyi.com/api/openapi.json)

## Also Available

| Platform | Install | Link |
|----------|---------|------|
| **npm** | `npm install barcodefyi` | [npm](https://www.npmjs.com/package/barcodefyi) |
| **Go** | `go get github.com/fyipedia/barcodefyi-go` | [pkg.go.dev](https://pkg.go.dev/github.com/fyipedia/barcodefyi-go) |
| **Rust** | `cargo add barcodefyi` | [crates.io](https://crates.io/crates/barcodefyi) |
| **Ruby** | `gem install barcodefyi` | [rubygems.org](https://rubygems.org/gems/barcodefyi) |
| **MCP** | `uvx --from "barcodefyi[mcp]" python -m barcodefyi.mcp_server` | [Config](#mcp-server-claude-cursor-windsurf) |

## Tag FYI Family

Part of the [FYIPedia](https://fyipedia.com) open-source developer tools ecosystem -- automatic identification and data capture technologies.

| Site | Domain | Focus |
|------|--------|-------|
| **BarcodeFYI** | [barcodefyi.com](https://barcodefyi.com) | **518 records -- barcode symbologies, standards, GS1 prefixes** |
| QRCodeFYI | [qrcodefyi.com](https://qrcodefyi.com) | 425 records -- QR code types, versions, encoding modes |
| NFCFYI | [nfcfyi.com](https://nfcfyi.com) | 288 records -- NFC chips, NDEF records, standards |
| BLEFYI | [blefyi.com](https://blefyi.com) | 261 records -- BLE chips, GATT profiles, beacons |
| RFIDFYI | [rfidfyi.com](https://rfidfyi.com) | 318 records -- RFID tags, frequency bands, EPC schemes |
| SmartCardFYI | [smartcardfyi.com](https://smartcardfyi.com) | 280 records -- smart cards, EMV, Java Card, platforms |

## FYIPedia Developer Tools

| Package | PyPI | npm | Description |
|---------|------|-----|-------------|
| **barcodefyi** | [PyPI](https://pypi.org/project/barcodefyi/) | [npm](https://www.npmjs.com/package/barcodefyi) | **Barcode symbologies, standards -- [barcodefyi.com](https://barcodefyi.com)** |
| qrcodefyi | [PyPI](https://pypi.org/project/qrcodefyi/) | [npm](https://www.npmjs.com/package/qrcodefyi) | QR code types, versions, encoding -- [qrcodefyi.com](https://qrcodefyi.com) |
| nfcfyi | [PyPI](https://pypi.org/project/nfcfyi/) | [npm](https://www.npmjs.com/package/nfcfyi) | NFC chips, NDEF, standards -- [nfcfyi.com](https://nfcfyi.com) |
| blefyi | [PyPI](https://pypi.org/project/blefyi/) | [npm](https://www.npmjs.com/package/blefyi) | BLE profiles, beacons, chips -- [blefyi.com](https://blefyi.com) |
| rfidfyi | [PyPI](https://pypi.org/project/rfidfyi/) | [npm](https://www.npmjs.com/package/rfidfyi) | RFID tags, readers, frequencies -- [rfidfyi.com](https://rfidfyi.com) |
| smartcardfyi | [PyPI](https://pypi.org/project/smartcardfyi/) | [npm](https://www.npmjs.com/package/smartcardfyi) | Smart cards, EMV, platforms -- [smartcardfyi.com](https://smartcardfyi.com) |

## License

MIT
