Skip to content
LabelZoom Docs

Python Quickstart

Install

Section titled “Install”
Terminal window
pip install labelzoom-sdk

Python 3.10+. Fully typed (py.typed), sync and async clients, one dependency (httpx). The distribution is labelzoom-sdk; the import is labelzoom.

Convert ZPL to PDF

Section titled “Convert ZPL to PDF”

An API key is optional — without one you get the free tier.

from pathlib import Path
from labelzoom import LabelZoomClient


with LabelZoomClient() as client:       # reads LABELZOOM_API_KEY; anonymous if unset
    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)

result.content is authoritative — five of the thirteen targets are binary. result.text decodes it with the response charset for the textual ones (zpl, xml, json).

Options are keyword arguments with the API’s nesting flattened by underscores: label.width becomes label_width, pdf.pageNumber becomes pdf_page_number. Only options you actually set are sent, so a change to a server default reaches you without an SDK upgrade.

Passing the key explicitly, or forcing anonymous:

client = LabelZoomClient("lz_live_...")
from_env = LabelZoomClient()            # reads LABELZOOM_API_KEY
anonymous = LabelZoomClient(None)       # forces anonymous, ignoring the env

Omitting the argument and passing None mean different things on purpose: omitting it consults the environment, None suppresses that fallback.

Converting a PDF to ZPL

Section titled “Converting a PDF to ZPL”
result = client.convert(
    "pdf", "zpl",
    Path("shipping-label.pdf").read_bytes(),
    label_width=4, label_height=6,
    pdf_page_number=0,                  # 0-based; omit for every page
)
zpl = result.text

jpg and url are source-only, and the type system says so — client.convert("pdf", "url", body) is a mypy error, not a runtime 404. The printer languages epl, ipl, tspl, dpl and sbpl are targets; read result.content for those, since EPL and TSPL can inline raw binary.

Async

Section titled “Async”

AsyncLabelZoomClient is a mirror, not a wrapper — same arguments, same behaviour, awaited.

import asyncio
from labelzoom import AsyncLabelZoomClient


async def main() -> None:
    async with AsyncLabelZoomClient() as client:
        result = await client.convert("zpl", "pdf", zpl, dpi=203)
        print(result.status, result.content_type, len(result.content))


asyncio.run(main())

Filling variable fields

Section titled “Filling variable fields”

Each record produces one label:

result = client.convert(
    "zpl", "pdf", template,
    data=[{"name": "ACME Corp", "sku": "12345"},
          {"name": "Globex", "sku": "67890"}],
)                                       # a 2-page PDF

Calling the REST API directly

Section titled “Calling the REST API directly”

The SDK is a wrapper over one HTTP endpoint; requests works just as well.

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)
print("Wrote label.pdf")

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

Notes

Section titled “Notes”