Skip to content
LabelZoom Docs

Java Quickstart

Install

Section titled “Install”
implementation 'com.labelzoom:labelzoom-sdk:1.0.0'
<dependency>
    <groupId>com.labelzoom</groupId>
    <artifactId>labelzoom-sdk</artifactId>
    <version>1.0.0</version>
</dependency>

Java 17+, published to Maven Central. Zero runtime dependencies — deliberately: this SDK gets dropped into WMS, ERP and TMS deployments whose classpaths are already crowded, and a transitive Jackson or Gson is a real source of version conflicts. The small amount of JSON it needs is built in.

Convert ZPL to PDF

Section titled “Convert ZPL to PDF”

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

import com.labelzoom.sdk.ConversionResult;
import com.labelzoom.sdk.LabelZoomClient;
import java.nio.file.Path;


public class LabelZoomQuickstart {
    public static void main(String[] args) throws Exception {
        // reads LABELZOOM_API_KEY; anonymous if unset
        try (LabelZoomClient client = LabelZoomClient.builder().build()) {
            ConversionResult result = client.convert()
                    .fromZpl("^XA^FO50,50^ADN,36,20^FDLabelZoom^FS^XZ")
                    .toPdf()
                    .withLabelSize(4f, 6f)      // inches
                    .withDpi(203)
                    .execute();


            result.save(Path.of("label.pdf"));
            System.out.println("Wrote label.pdf");
        }
    }
}

result.bytes() is authoritative — five of the thirteen targets are binary. result.text() decodes it with the response charset for the textual ones, and result.save(Path) writes it straight to disk.

Passing the key explicitly, or forcing anonymous:

LabelZoomClient.builder().apiKey("lz_live_...").build();
LabelZoomClient.builder().build();            // reads LABELZOOM_API_KEY
LabelZoomClient.builder().apiKey("").build(); // forces anonymous

Converting a PDF to ZPL

Section titled “Converting a PDF to ZPL”
ConversionResult result = client.convert()
        .fromFile(SourceFormat.PDF, Path.of("shipping-label.pdf"))
        .toZpl()
        .withLabelSize(4f, 6f)      // inches
        .withPdfPage(0)             // 0-based; omit for every page
        .execute();


System.out.println(result.text());

SourceFormat and TargetFormat are distinct enums, so toEpl() does not exist and to(SourceFormat.PDF) does not compile. JPG and URL are source-only on the server, and the type system says so rather than letting you find out from a 404.

The printer languages epl, ipl, tspl, dpl and sbpl are targets — fromPdf(bytes).toEpl() is a real conversion. Read result.bytes() rather than the decoded text for those: EPL’s GW and TSPL’s BITMAP commands inline raw binary.

Filling variable fields

Section titled “Filling variable fields”

Each record produces one label:

ConversionResult result = client.convert()
        .fromZpl(template)
        .toPdf()
        .withData(
                Map.of("name", "ACME Corp", "sku", "12345"),
                Map.of("name", "Globex", "sku", "67890"))
        .execute();                 // 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; the built-in HttpClient (Java 11+) works just as well.

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.file.Path;


String zpl = "^XA^FO50,50^ADN,36,20^FDLabelZoom^FS^XZ";
String apiKey = System.getenv("LABELZOOM_API_KEY");


HttpClient client = HttpClient.newHttpClient();
HttpRequest.Builder builder = HttpRequest.newBuilder()
    .uri(URI.create("https://api.labelzoom.com/api/v2/convert/zpl/to/pdf"
        + "?label.width=4&label.height=6&dpi=203"))
    .header("Content-Type", "text/plain")
    .POST(HttpRequest.BodyPublishers.ofString(zpl));


// The API key is optional — omit the Authorization header if it isn't set.
if (apiKey != null && !apiKey.isBlank()) {
    builder.header("Authorization", "Bearer " + apiKey);
}


HttpResponse<Path> response = client.send(
    builder.build(), HttpResponse.BodyHandlers.ofFile(Path.of("label.pdf")));


if (response.statusCode() != 200) {
    throw new RuntimeException("Conversion failed: " + response.statusCode());
}

To convert a PDF to ZPL, point the URI at /convert/pdf/to/zpl, send BodyPublishers.ofFile(...) with Content-Type: application/pdf, and read the response with BodyHandlers.ofString().

Notes

Section titled “Notes”