Java quickstart

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

Before you begin

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

Install the SDK

Add the com.labelzoom:labelzoom-sdk artifact from Maven Central to your build.

Gradle:

implementation 'com.labelzoom:labelzoom-sdk:1.1.0'

Maven:

<dependency>
    <groupId>com.labelzoom</groupId>
    <artifactId>labelzoom-sdk</artifactId>
    <version>1.1.0</version>
</dependency>

Convert ZPL to PDF

Save the following program as LabelZoomQuickstart.java:

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 {
        try (LabelZoomClient client = LabelZoomClient.builder().build()) {  // reads LABELZOOM_API_KEY
            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"));
        }
    }
}

The SDK reads your API key from the LABELZOOM_API_KEY environment variable. To pass a key explicitly, use LabelZoomClient.builder().apiKey("API_KEY").build(). Create one client for your application and reuse it.

Run the program. It writes label.pdf.

Convert a PDF to ZPL

import com.labelzoom.sdk.SourceFormat;

ConversionResult result = client.convert()
        .fromFile(SourceFormat.PDF, Path.of("shipping-label.pdf"))
        .toZpl()
        .withPdfPage(0)                 // 0-based; omit to convert every page
        .execute();

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

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

Fill variable fields

import java.util.Map;

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

ConversionResult result = client.convert()
        .fromZpl(template)
        .toZpl()
        .withData(                      // one label per record
                Map.of("name", "ACME Corp", "sku", "12345"),
                Map.of("name", "Globex", "sku", "67890"))
        .execute();

System.out.println(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

import com.labelzoom.sdk.LabelZoomException;

try {
    client.convert().fromZpl("^XA^FO50,50^ADN,36,20^FDLabelZoom^FS^XZ").toPdf().execute();
} catch (LabelZoomException e) {
    System.err.printf("HTTP %d, request ID %s: %s%n",
            e.statusCode(), e.requestId().orElse("none"), e.getMessage());
}

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

Call the API without the SDK

To call the API with the built-in HttpClient instead of the SDK, send the label as the request body:

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().

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.