Python quickstart

This page shows how to convert labels from Python with the LabelZoom Python SDK.

Before you begin

Install Python 3.10 or later.
Optional: Get an API key. Without one, output has a watermark. See Authentication.

Install the SDK

Install the labelzoom-sdk package from PyPI:

pip install labelzoom-sdk

The package is named labelzoom-sdk, but you import it as labelzoom.

Convert ZPL to PDF

Save the following program as convert.py:

from pathlib import Path
from labelzoom import LabelZoomClient

with LabelZoomClient() as client:       # reads LABELZOOM_API_KEY
    result = client.convert(
        "zpl", "pdf",
        "^XA^FO50,50^ADN,36,20^FDLabelZoom^FS^XZ",
        label_width=4, label_height=6,  # inches
        dpi=203,
    )

Path("label.pdf").write_bytes(result.content)

The SDK reads your API key from the LABELZOOM_API_KEY environment variable. To pass a key explicitly, use LabelZoomClient("API_KEY").

Options are snake_case keyword arguments: label.width becomes label_width, and pdf.pageNumber becomes pdf_page_number. For asyncio code, AsyncLabelZoomClient has the same methods; await them.

Run the program with python convert.py. It writes label.pdf.

Convert a PDF to ZPL

with LabelZoomClient() as client:
    result = client.convert(
        "pdf", "zpl",
        Path("shipping-label.pdf").read_bytes(),
        pdf_page_number=0,              # 0-based; omit to convert every page
    )

print(result.text)

Write PDF, image, and printer-language (EPL, IPL, TSPL, DPL, SBPL) output as bytes (result.content), not text; see Binary output.

Fill variable fields

template = "^XA^FO50,50^A0N,30,30^FD{name}^FS^FO50,100^A0N,30,30^FD{sku}^FS^XZ"

with LabelZoomClient() as client:
    result = client.convert(
        "zpl", "zpl", template,
        data=[                          # one label per record
            {"name": "ACME Corp", "sku": "12345"},
            {"name": "Globex", "sku": "67890"},
        ],
    )

print(result.text)

Each placeholder, such as {name}, takes its value from the matching key in each record; see Merge fields for the placeholder syntax.

Handle errors

from labelzoom import LabelZoomClient, LabelZoomError

with LabelZoomClient() as client:
    try:
        client.convert("zpl", "pdf", "^XA^FO50,50^ADN,36,20^FDLabelZoom^FS^XZ")
    except LabelZoomError as error:
        print(f"HTTP {error.status}, request ID {error.request_id}: {error.message}")

The SDK retries 429 and 5xx responses automatically before it raises. For status codes, see Errors.

Call the API without the SDK

To call the API with requests instead of the SDK, send the label as the request body:

import os
import requests

zpl = "^XA^FO50,50^ADN,36,20^FDLabelZoom^FS^XZ"

# The API key is optional. Omit the Authorization header if it isn't set.
headers = {"Content-Type": "text/plain"}
api_key = os.environ.get("LABELZOOM_API_KEY")
if api_key:
    headers["Authorization"] = f"Bearer {api_key}"

response = requests.post(
    "https://api.labelzoom.com/api/v2/convert/zpl/to/pdf",
    params={"label.width": 4, "label.height": 6, "dpi": 203},
    headers=headers,
    data=zpl,
)
response.raise_for_status()

with open("label.pdf", "wb") as f:
    f.write(response.content)

To convert a PDF to ZPL, post the file’s bytes to /convert/pdf/to/zpl with Content-Type: application/pdf, and read response.text.

To set options, send one params query parameter that holds JSON, or use dot notation such as label.width=4. Accept can be */*, the target’s media type, or a wildcard such as image/*. See Conversion parameters.