Payloads & QR Encoding
payload · encoding

Payload

What to encode

The payload object is required for generate, measure and validate. Two payload types are available.

{ "payload": { "text": "https://www.chilkatsoft.com" } }

{ "payload": { "type": "binary",
               "base64": "AAECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8=" } }

Encoding mode

Numeric, alphanumeric and byte

QR has compact encodings for digits and for an upper-case alphanumeric set. By default Chilkat picks the densest mode the whole payload fits. The selected mode is reported in symbols[0].selectedEncoding.mode.

Force a mode with encoding.qr.mode ("auto", "numeric", "alphanumeric", "byte"). A mode the payload cannot use — for example numeric for "abc" — is rejected with conflictingOptions at /encoding/qr/mode. kanji is reserved and not yet available. Each payload is encoded as one segment in v11.7.0; encoding.qr.optimizeSegments is accepted for forward compatibility.

{ "payload": { "text": "20261024" }, "encoding": { "qr": { "mode": "byte" } } }

Error correction

Level L, M, Q or H

Reed–Solomon error correction lets a damaged or partly obscured symbol still be read. Higher levels cost capacity, so the same payload often needs a larger version.

{ "payload": { "text": "https://www.chilkatsoft.com" },
  "encoding": { "qr": { "errorCorrection": "H" } } }

boostErrorCorrection

When the chosen version has spare capacity, "boostErrorCorrection": true raises the level as far as the payload still fits in the same version, so robustness improves at no cost in size. The level actually used is reported in selectedEncoding.errorCorrection.

{ "payload": { "text": "x" }, "encoding": { "qr": { "boostErrorCorrection": true } } }
// response: "selectedEncoding": { "version": 1, "errorCorrection": "H", ... }

Version (size)

Automatic, exact, or bounded

A QR version is its size in modules: version 1 is 21 × 21, each further version adds 4 modules, up to version 40 at 177 × 177. By default the smallest version that holds the payload at the selected error-correction level is used.

{ "payload": { "text": "SKU-00042" }, "encoding": { "qr": { "minVersion": 4, "maxVersion": 4 } } }

Mask

Automatic by the standard penalty rules, or explicit

Before a QR symbol is finished, one of eight mask patterns is XOR-ed over the data area to break up large uniform regions. ISO/IEC 18004 scores each candidate with four penalty rules and takes the lowest score; Chilkat does exactly that for "auto" (ties are resolved deterministically, so the same request always gives the same symbol). The chosen mask is reported in selectedEncoding.mask.

Set encoding.qr.mask to 0–7 to force a pattern — useful for regression tests or to reproduce a symbol generated elsewhere. Values outside 0–7 are outOfRange.

{ "payload": { "text": "https://www.chilkatsoft.com" }, "encoding": { "qr": { "mask": 5 } } }

Character set

UTF-8 and ECI

Text is always encoded as UTF-8 bytes. By default no ECI (Extended Channel Interpretation) header is emitted, which is what virtually every reader expects. Set encoding.eci to 26 to declare UTF-8 explicitly inside the symbol.

{ "payload": { "text": "日本語のテキスト" }, "encoding": { "eci": 26 } }

Structured append

Split a large payload across up to 16 symbols

A structured-append set is a sequence of QR symbols that a reader reassembles into one payload. Each part carries its index, the total count and a parity byte computed over the whole payload. Chilkat splits the payload as evenly as possible.

The response has one symbols[] entry, one measurements[] entry and one outputs[] entry per part, in order. Each symbol reports structuredAppend: { "index", "total", "parity" } (index is 0-based) and its own payloadBytes.

{
  "payload":  { "text": "...a 120-character string..." },
  "encoding": { "structuredAppend": { "enabled": true, "symbolCount": 3 } },
  "output":   { "return": "none", "pathTemplate": "/labels/part{index}.png" }
}

{
  "symbols": [
    { "symbology": "qr", "selectedEncoding": { "version": 3, "errorCorrection": "M", "mask": 2, "mode": "byte" },
      "dimensions": { "modulesWide": 29, "modulesHigh": 29, ... },
      "structuredAppend": { "index": 0, "total": 3, "parity": 120 }, "payloadBytes": 40 },
    { ... "structuredAppend": { "index": 1, "total": 3, "parity": 120 }, "payloadBytes": 40 },
    { ... "structuredAppend": { "index": 2, "total": 3, "parity": 120 }, "payloadBytes": 40 }
  ],
  "outputs": [
    { "index": 0, "format": "png", ..., "path": "/labels/part1.png" },
    { "index": 1, "format": "png", ..., "path": "/labels/part2.png" },
    { "index": 2, "format": "png", ..., "path": "/labels/part3.png" }
  ], ...
}

Reading the result

selectedEncoding and dimensions

The response never echoes "auto": selectedEncoding holds the resolved choices, so you always know exactly what was generated.

int version = jsonOut.IntOf("symbols[0].selectedEncoding.version");
string level = jsonOut.StringOf("symbols[0].selectedEncoding.errorCorrection");
int modules = jsonOut.IntOf("symbols[0].dimensions.modulesWide");
int numParts = jsonOut.SizeOfArray("symbols");   // > 1 for structured append

int version = jsonOut.IntOf("symbols[0].selectedEncoding.version");
const char *level = jsonOut.stringOf("symbols[0].selectedEncoding.errorCorrection");
int modules = jsonOut.IntOf("symbols[0].dimensions.modulesWide");
int numParts = jsonOut.SizeOfArray("symbols");   // > 1 for structured append

version = jsonOut.IntOf("symbols[0].selectedEncoding.version")
level = jsonOut.StringOf("symbols[0].selectedEncoding.errorCorrection")
modules = jsonOut.IntOf("symbols[0].dimensions.modulesWide")
numParts = jsonOut.SizeOfArray("symbols")   # > 1 for structured append