Barcode Types Reference¶
GET /v1/barcode/types returns the live registry of supported 1D symbologies. This page explains each entry, the data each one accepts, and how the API handles checksums — so you can pick the right barcode_type on the first try instead of debugging a 400.
Endpoint¶
GET /v1/barcode/types
Base URL: https://barcode.toolkitapi.io
Requires an X-API-Key header. Returns:
{
"total": 11,
"types": [
{
"name": "ean13",
"description": "EAN-13 — European Article Number (retail)",
"data_format": "12 or 13 digits (checksum auto-calculated)",
"max_length": 13
}
]
}
Supported symbologies¶
barcode_type |
Standard | Accepted data | max_length |
|---|---|---|---|
code128 |
Code 128 | Any ASCII characters | none |
code39 |
Code 39 | A-Z, 0-9, space, - . $ / + % |
none |
ean13 |
EAN-13 | 12 or 13 digits (checksum auto-calculated) | 13 |
ean8 |
EAN-8 | 7 or 8 digits (checksum auto-calculated) | 8 |
ean14 |
EAN-14 | 13 or 14 digits (checksum auto-calculated) | 14 |
upca |
UPC-A | 11 or 12 digits (checksum auto-calculated) | 12 |
isbn13 |
ISBN-13 | 12 or 13 digits starting with 978/979 |
13 |
isbn10 |
ISBN-10 | 9 or 10 characters (digits + optional X check) |
10 |
issn |
ISSN | 7 or 8 digits for periodicals | 8 |
pzn |
PZN (Pharmazentralnummer) | 6 or 7 digits | 7 |
itf |
Interleaved 2 of 5 | Even number of digits | none |
Note
max_length is null for code128, code39, and itf — but the request body still caps data at 256 characters (BarcodeGenerateRequest.data, max_length=256). A longer value fails schema validation with 422 before the encoder is ever called.
Checksum behaviour¶
For the numeric retail and book symbologies the check digit is computed for you. Pass the short form and the API appends it:
| Type | You send | Encoded |
|---|---|---|
ean13 |
12 digits | 13 digits, check digit added |
ean8 |
7 digits | 8 digits |
ean14 |
13 digits | 14 digits |
upca |
11 digits | 12 digits |
isbn13 |
12 digits | 13 digits |
issn |
7 digits | 8 digits |
pzn |
6 digits | 7 digits |
If you send the full-length form the API accepts it only when the trailing digit is already the correct checksum. Send a wrong check digit and the encoder raises a validation error (400) rather than silently "fixing" it.
code128, code39, and itf have no numeric checksum requirement; itf is otherwise strict about even length — pad with a leading zero.
Choosing a type¶
| Use case | Type | Why |
|---|---|---|
| Internal asset tags, arbitrary strings | code128 |
Dense, full ASCII, no length bookkeeping |
| Legacy industrial / logistics scanners | code39 |
Widely supported by old readers; uppercase only |
| Retail products (EU) | ean13 |
Required on EU retail packaging |
| Small retail packaging | ean8 |
Fits tiny labels |
| Cartons / pallets / outer cases | ean14 (or itf) |
GS1 logistics standard |
| Retail products (North America) | upca |
Required on NA retail packaging |
| Books | isbn13 (modern), isbn10 (legacy) |
Printed on back covers |
| Magazines / journals | issn |
Periodical identifier |
| Pharmaceuticals (Germany) | pzn |
German pharma standard |
| Numeric cartons read by ITF scanners | itf |
Fixed-width numeric encoding |
Request parameters (for context)¶
Barcode type is one field of a larger generate request:
| Field | Type | Default | Description |
|---|---|---|---|
data |
string | — | Data to encode, max 256 chars |
barcode_type |
string | code128 |
One of the 11 types above |
format |
string | png |
png or svg |
include_text |
boolean | true |
Render human-readable text under the bars |
fg_color |
string | #000000 |
Bar colour, hex (max 9 chars — #RRGGBBAA allowed) |
bg_color |
string | #ffffff |
Background colour, hex |
module_height |
number | 15.0 |
Bar height in mm, 5.0–50.0 |
quiet_zone |
number | 6.5 |
Quiet zone width in mm, 0.0–20.0 |
Full endpoint documentation: Barcodes.
Examples¶
List available types¶
curl "https://barcode.toolkitapi.io/v1/barcode/types" \
-H "X-API-Key: YOUR_KEY"
const resp = await fetch("https://barcode.toolkitapi.io/v1/barcode/types", {
headers: { "X-API-Key": "YOUR_KEY" },
});
const { total, types } = await resp.json();
console.log(`${total} symbologies`);
for (const t of types) console.log(t.name.padEnd(8), t.data_format);
from toolkitapi import Barcode
with Barcode(api_key="tk_...") as bc:
catalog = bc.types()
for t in catalog["types"]:
print(f'{t["name"]:<8} {t["data_format"]}')
Generate with a computed check digit¶
# 12 digits in — the API appends the EAN-13 check digit
curl -X POST "https://barcode.toolkitapi.io/v1/barcode/generate" \
-H "X-API-Key: YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"data": "400638133393", "barcode_type": "ean13", "format": "png", "module_height": 20}'
from toolkitapi import Barcode
with Barcode(api_key="tk_...") as bc:
# ISBN-13 for a book — send 12 digits, checksum is appended
result = bc.generate(
data="978030640615",
barcode_type="isbn13",
format="svg",
include_text=True,
)
open("book.svg", "w").write(result["svg"])
const resp = await fetch("https://barcode.toolkitapi.io/v1/barcode/generate", {
method: "POST",
headers: { "X-API-Key": "YOUR_KEY", "Content-Type": "application/json" },
body: JSON.stringify({
data: "012345678905", // UPC-A: 11 digits + computed check
barcode_type: "upca",
format: "png",
}),
});
const { image } = await resp.json();
const buf = Buffer.from(image, "base64");
Compute a check digit yourself (pre-flight validation)¶
def ean13_check_digit(payload: str) -> str:
"""Return the EAN-13/UPC-A/ISBN-13 check digit for a 12-digit payload."""
if len(payload) != 12 or not payload.isdigit():
raise ValueError("payload must be exactly 12 digits")
total = sum((3 if i % 2 else 1) * int(d) for i, d in enumerate(payload))
return str((10 - total % 10) % 10)
print(ean13_check_digit("400638133393")) # '0' → full code 4006381333930
Errors¶
| Status | Condition |
|---|---|
400 |
Data not encodable for the chosen symbology (bad chars, wrong length, odd-length itf, wrong check digit) |
422 |
Schema violation — data over 256 chars, unknown barcode_type, out-of-range module_height/quiet_zone |
401 |
Missing or invalid API key |
Testing¶
- Generate with your production symbology and the same data lengths you expect in the wild.
- Decode the output with
POST /v1/barcode/decode(orPOST /v1/qr/decode) to confirm round-trip fidelity. - Print at the real label size and scan with the actual hardware and a phone camera —
quiet_zoneunder ~5 mm is the most common cause of scan failures at small sizes.
See also¶
- Barcodes — generate endpoint and styling options
- Bulk & Decode — batch generation and image decoding
- QR Codes — 2D codes with logos and custom module shapes