Quickstart

This page shows how to convert a ZPL label to PDF with an official SDK.

Before you begin

• Install one of the runtimes listed in Install the SDK.
• Optional: Get an API key. Without one, output has a watermark. See Authentication.

Install the SDK

JavaScript

npm install @labelzoom/sdk

Requires Node.js 20 or later. See the JavaScript quickstart.

Python

pip install labelzoom-sdk

Requires Python 3.10 or later. See the Python quickstart.

Java

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

Requires Java 17 or later. See the Java quickstart.

C#

dotnet add package LabelZoom.Sdk

Requires .NET Framework 4.6.1, .NET Core 2.0, .NET 5, or later. See the C# quickstart.

PHP

composer require labelzoom/sdk

Requires PHP 8.1 or later. See the PHP quickstart.

Go

go get github.com/labelzoom/labelzoom-sdk/go

Requires Go 1.23 or later. See the Go quickstart.

Ruby

gem install labelzoom

Requires Ruby 3.1 or later. See the Ruby quickstart.

Rust

cargo add labelzoom

Requires Rust 1.85 or later. See the Rust quickstart.

Convert ZPL to PDF

JavaScript

import { writeFile } from 'node:fs/promises';
import { LabelZoomClient } from '@labelzoom/sdk';

const client = new LabelZoomClient();   // reads LABELZOOM_API_KEY

const result = await client.convert()
  .fromZpl('^XA^FO50,50^ADN,36,20^FDLabelZoom^FS^XZ')
  .toPdf()
  .withLabelSize(4, 6)                  // inches
  .withDpi(203)
  .execute();

await writeFile('label.pdf', result.bytes);

Python

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)

Java

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"));
}

C#

using LabelZoom.Sdk;

using var client = new LabelZoomClient();   // reads LABELZOOM_API_KEY

var result = await client.Convert()
    .FromZpl("^XA^FO50,50^ADN,36,20^FDLabelZoom^FS^XZ")
    .ToPdf()
    .WithLabelSize(widthInches: 4f, heightInches: 6f)
    .WithDpi(203)
    .ExecuteAsync();

result.Save("label.pdf");

PHP

<?php

require __DIR__ . '/vendor/autoload.php';

use LabelZoom\Sdk\LabelZoomClient;

$client = new LabelZoomClient();        // reads LABELZOOM_API_KEY

$result = $client->convert()
    ->fromZpl('^XA^FO50,50^ADN,36,20^FDLabelZoom^FS^XZ')
    ->toPdf()
    ->withLabelSize(widthInches: 4, heightInches: 6)
    ->withDpi(203)
    ->execute();

$result->save('label.pdf');

Go

client, err := labelzoom.New()          // reads LABELZOOM_API_KEY
if err != nil {
  log.Fatal(err)
}

result, err := client.Convert(context.Background(), labelzoom.ConvertRequest{
  From: labelzoom.SourceZPL,
  To:   labelzoom.TargetPDF,
  Body: []byte("^XA^FO50,50^ADN,36,20^FDLabelZoom^FS^XZ"),
  Options: &labelzoom.Options{
    Label: &labelzoom.LabelSize{Width: labelzoom.Ptr(4.0), Height: labelzoom.Ptr(6.0)},
    DPI:   labelzoom.Ptr(203),
  },
})
if err != nil {
  log.Fatal(err)
}

if err := result.Save("label.pdf"); err != nil {
  log.Fatal(err)
}

Ruby

require "labelzoom"

client = LabelZoom::Client.new        # reads LABELZOOM_API_KEY

result = client.convert(
  :zpl, :pdf,
  "^XA^FO50,50^ADN,36,20^FDLabelZoom^FS^XZ",
  label: { width: 4, height: 6 },     # inches
  dpi: 203
)

result.save("label.pdf")

Rust

use labelzoom::{ConversionOptions, ConvertRequest, LabelZoomClient, SourceFormat, TargetFormat};

let client = LabelZoomClient::new();    // reads LABELZOOM_API_KEY

let result = client.convert(
    &ConvertRequest::new(
        SourceFormat::Zpl,
        TargetFormat::Pdf,
        "^XA^FO50,50^ADN,36,20^FDLabelZoom^FS^XZ",
    )
    .options(ConversionOptions::new().label_size(4.0, 6.0).dpi(203)),
)?;

result.save("label.pdf")?;

Check the result

Open label.pdf. Without an API key or a paid plan, the label has a watermark.

Call the API without an SDK

Every conversion is one HTTP request:

POST https://api.labelzoom.com/api/v2/convert/{source}/to/{target}

Send the label as the request body. The response body is the converted file. To convert label.zpl to PDF with curl, run the following command:

curl -X POST "https://api.labelzoom.com/api/v2/convert/zpl/to/pdf?label.width=4&label.height=6" \
  -H "Authorization: Bearer API_KEY" \
  -H "Content-Type: text/plain" \
  -H "Accept: */*" \
  --data-binary @label.zpl \
  --output label.pdf

Replace API_KEY with your key, or omit the Authorization header to convert on the free tier. Accept: */* works for every target; the target’s media type or a wildcard such as image/* also works. Use --data-binary so that curl sends the file unchanged.

Each language quickstart shows the same request with that language’s HTTP client, for example Python.

Set options as query parameters:

Parameter	Description
label.width	Label width in inches. Omit both label.width and label.height to use the label’s own size.
label.height	Label height in inches.
dpi	Print density in dots per inch. The default is 203.

For every parameter, see Conversion parameters. For the {source} and {target} values and the Content-Type that each source needs, see Supported formats. To try requests in your browser, use the Swagger UI.

What’s next

• Authentication
• Conversion parameters
• Supported formats
• Errors