ZPL Web Service

Introduction

The Labelary ZPL rendering engine is available as an online service, and can be invoked via a simple, easy-to-use RESTful API:

GET http://api.labelary.com/v1/printers/{dpmm}/labels/{width}x{height}/{index}/{zpl}

By default the service returns PNG images:

Accept: image/png

However, PDF documents can also be requested:

Accept: application/pdf

You can also use POST instead of GET by moving the ZPL out of the URL and into the POST message body (see below for examples).

The POST method is useful when:

  1. your ZPL is very large (since URLs are limited to 3,000 characters or so), or
  2. you are running into character encoding issues, or
  3. your ZPL contains embedded binary data.

Parameters

dpmm
The desired print density, in dots per millimeter.
Valid values are "6dpmm", "8dpmm", "12dpmm", and "24dpmm". See your printer's documentation for more information.
width
The label width, in inches. Any numeric value may be used.
height
The label height, in inches. Any numeric value may be used.
index
The label index (base 0).
Some ZPL code will generate multiple labels, and this parameter can be used to access these different labels. In general though, the value of this parameter will be 0 (zero).
Note that this parameter is optional when requesting PDF documents. If not specified, the resultant PDF document will contain all labels (one label per page).
zpl
The ZPL code to render.
Note that if you are using the GET method and the ZPL contains any hashes (#), they should be encoded (%23) in order to avoid parts of the ZPL being incorrectly interpreted as URL fragments.

Limits

As a shared service, the Labelary API incorporates a number of usage limits which ensure that no single user can negatively impact the workloads of other users.

  • Maximum 5 requests per second per client. Additional requests result in a HTTP 429 (Too Many Requests) error.
  • Maximum 50 labels per request. Additional labels result in a HTTP 413 (Payload Too Large) error.
  • Maximum label size of 15 x 15 inches. Larger labels result in a HTTP 400 (Bad Request) error.
  • Maximum embedded object size of 5MB, for e.g. ~DU and ~DY. Larger embedded objects result in a HTTP 400 (Bad Request) error.
  • Maximum embedded image dimensions of 2,000 x 2,000 pixels, for e.g. ~DG and ~DY. Larger embedded images result in a HTTP 400 (Bad Request) error.

The image conversion service (image → ZPL) also has the following limits:

  • Maximum input image file size of 200 KB. Larger files result in a HTTP 400 (Bad Request) error.
  • Maximum input image dimensions of 2,000 x 2,000 pixels. Larger image sizes result in a HTTP 400 (Bad Request) error.

Note that these limits may be changed as needed in order to ensure smooth operation of the service for all users.

If these limits are too restrictive for your intended use, you may want to consider licensing Labelary for private on-premise use.

Live Examples

Some live examples that use GET requests to convert the ZPL in the URLs into PNG images:

curl Examples

Some curl examples:

  • Using the GET method:

    curl --get http://api.labelary.com/v1/printers/8dpmm/labels/4x6/0/ --data-urlencode "^xa^cfa,50^fo100,100^fdHello World^fs^xz" > label.png

  • Using the POST method (with application/x-www-form-urlencoded content):

    curl --request POST http://api.labelary.com/v1/printers/8dpmm/labels/4x6/0/ --data "^xa^cfa,50^fo100,100^fdHello World^fs^xz" > label.png

  • Using the POST method (with multipart/form-data content):

    curl --request POST http://api.labelary.com/v1/printers/8dpmm/labels/4x6/0/ --form file=@label.zpl > label.png

  • Using the POST method (with multipart/form-data content), requesting a PDF file instead of a PNG image:

    curl --request POST http://api.labelary.com/v1/printers/8dpmm/labels/4x6/0/ --form file=@label.zpl --header "Accept: application/pdf" > label.pdf

PowerShell Examples

  • Using the POST method (with application/x-www-form-urlencoded content) to request a PNG image:

    Invoke-RestMethod `
    -Method Post `
    -Uri http://api.labelary.com/v1/printers/8dpmm/labels/4x6/0/ `
    -ContentType "application/x-www-form-urlencoded" `
    -InFile label.zpl `
    -OutFile label.png

  • Using the POST method (with application/x-www-form-urlencoded content) to request a PDF file:

    Invoke-RestMethod `
    -Method Post `
    -Uri http://api.labelary.com/v1/printers/8dpmm/labels/4x6/0/ `
    -ContentType "application/x-www-form-urlencoded" `
    -Headers @{"Accept" = "application/pdf"} `
    -InFile label.zpl `
    -OutFile label.pdf

Java Example

A Java example that uses the Jersey REST client to send a POST request to convert a ZPL string to a PDF file:

String zpl = "^xa^cfa,50^fo100,100^fdHello World^fs^xz";

Client client = ClientBuilder.newBuilder().register(MultiPartFeature.class).build();
// adjust print density (8dpmm), label width (4 inches), label height (6 inches), and label index (0) as necessary
WebTarget target = client.target("http://api.labelary.com/v1/printers/8dpmm/labels/4x6/0/");
Builder request = target.request();
request.accept("application/pdf"); // omit this line to get PNG images back
Response response = request.post(Entity.entity(zpl, MediaType.APPLICATION_FORM_URLENCODED));

if (response.getStatus() == 200) {
    byte[] body = response.readEntity(byte[].class);
    File file = new File("label.pdf"); // change file name for PNG images
    Files.write(file.toPath(), body);
} else {
    String body = response.readEntity(String.class);
    System.out.println("Error: " + body);
}

Ruby Example

A Ruby example that uses a POST request to convert a ZPL string to a PDF file (courtesy Robert Coleman):

require 'net/http'

zpl = '^xa^cfa,50^fo100,100^fdHello World^fs^xz'

# adjust print density (8dpmm), label width (4 inches), label height (6 inches), and label index (0) as necessary
uri = URI 'http://api.labelary.com/v1/printers/8dpmm/labels/4x6/0/'
http = Net::HTTP.new uri.host, uri.port
request = Net::HTTP::Post.new uri.request_uri
request.body = zpl
request['Accept'] = 'application/pdf' # omit this line to get PNG images back
response = http.request request

case response
when Net::HTTPSuccess then
    File.open 'label.pdf', 'wb' do |f| # change file name for PNG images
        f.write response.body
    end
else
    puts "Error: #{response.body}"
end

Node.js Example

A Node.js example that uses a POST request to convert a ZPL string to a PDF file (courtesy Katy LaVallee):

var fs = require('fs');
var request = require('request');

var zpl = "^xa^cfa,50^fo100,100^fdHello World^fs^xz";

var options = {
    encoding: null,
    formData: { file: zpl },
    headers: { 'Accept': 'application/pdf' }, // omit this line to get PNG images back
    url: 'http://api.labelary.com/v1/printers/8dpmm/labels/4x6/0/' // adjust print density (8dpmm), label width (4 inches), label height (6 inches), and label index (0) as necessary
};

request.post(options, function(err, resp, body) {
    if (err) {
        return console.log(err);
    }
    var filename = 'label.pdf'; // change file name for PNG images
    fs.writeFile(filename, body, function(err) {
        if (err) {
            console.log(err);
        }
    });
});

C# Example

A C# example that uses a POST request to convert a ZPL string to a PDF file:

byte[] zpl = Encoding.UTF8.GetBytes("^xa^cfa,50^fo100,100^fdHello World^fs^xz");

// adjust print density (8dpmm), label width (4 inches), label height (6 inches), and label index (0) as necessary
var request = (HttpWebRequest) WebRequest.Create("http://api.labelary.com/v1/printers/8dpmm/labels/4x6/0/");
request.Method = "POST";
request.Accept = "application/pdf"; // omit this line to get PNG images back
request.ContentType = "application/x-www-form-urlencoded";
request.ContentLength = zpl.Length;

var requestStream = request.GetRequestStream();
requestStream.Write(zpl, 0, zpl.Length);
requestStream.Close();

try {
    var response = (HttpWebResponse) request.GetResponse();
    var responseStream = response.GetResponseStream();
    var fileStream = File.Create("label.pdf"); // change file name for PNG images
    responseStream.CopyTo(fileStream);
    responseStream.Close();
    fileStream.Close();
} catch (WebException e) {
    Console.WriteLine("Error: {0}", e.Status);
}

VB.NET Example

A VB.NET example that uses a POST request to convert a ZPL string to a PDF file:

Dim zpl() As Byte = Encoding.UTF8.GetBytes("^xa^cfa,50^fo100,100^fdHello World^fs^xz")

' adjust print density (8dpmm), label width (4 inches), label height (6 inches), and label index (0) as necessary
Dim request As HttpWebRequest = WebRequest.Create("http://api.labelary.com/v1/printers/8dpmm/labels/4x6/0/")
request.Method = "POST"
request.Accept = "application/pdf" ' omit this line to get PNG images back
request.ContentType = "application/x-www-form-urlencoded"
request.ContentLength = zpl.Length

Dim requestStream As Stream = request.GetRequestStream()
requestStream.Write(zpl, 0, zpl.Length)
requestStream.Close()

Try
    Dim response As HttpWebResponse = request.GetResponse()
    Dim responseStream As Stream = response.GetResponseStream()
    Dim fileStream As Stream = File.Create("label.pdf") ' change file name for PNG images
    responseStream.CopyTo(fileStream)
    responseStream.Close()
    fileStream.Close()
Catch e As WebException
    Console.WriteLine("Error: {0}", e.Status)
End Try

PHP Example

A PHP example that uses a POST request to convert a ZPL string to a PDF file:

<?php

$zpl = "^xa^cfa,50^fo100,100^fdHello World^fs^xz";

$curl = curl_init();
// adjust print density (8dpmm), label width (4 inches), label height (6 inches), and label index (0) as necessary
curl_setopt($curl, CURLOPT_URL, "http://api.labelary.com/v1/printers/8dpmm/labels/4x6/0/");
curl_setopt($curl, CURLOPT_POST, TRUE);
curl_setopt($curl, CURLOPT_POSTFIELDS, $zpl);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($curl, CURLOPT_HTTPHEADER, array("Accept: application/pdf")); // omit this line to get PNG images back
$result = curl_exec($curl);

if (curl_getinfo($curl, CURLINFO_HTTP_CODE) == 200) {
    $file = fopen("label.pdf", "w"); // change file name for PNG images
    fwrite($file, $result);
    fclose($file);
} else {
    print_r("Error: $result");
}

curl_close($curl);

?>

Advanced

Some advanced features provided by the Labelary API:

Rotate labels EXPERIMENTAL

Your ZPL template already defines a label rotation / orientation. Sometimes, however, the label orientation that is most suitable for your printer is not the orientation that you'd like to use during format conversion.

If this is the case, you can ask Labelary to rotate the label image by adding a X-Rotation HTTP header to the request. The value of this header should be the number of degrees to rotate the label clockwise, and may be one of 0, 90, 180 or 270.

This header is available for both PNG and PDF requests.

PDF with multiple labels

When requesting a PNG image, you can only get one label back at a time, even if your ZPL defines multiple labels. However, PDF files can contain more than one label. If you are requesting a PDF file and you would like it to contain all of the labels defined in your ZPL template, simply omit the index parameter from the request URL.

For example, instead of sending your request to this URL, which returns the label at index 0 (the first label):

http://api.labelary.com/v1/printers/8dpmm/labels/4x6/0/

You can omit the index and instead send your request to this URL:

http://api.labelary.com/v1/printers/8dpmm/labels/4x6/

Note that this option is only available for PDF requests.

PDF page size and page layout EXPERIMENTAL

By default, Labelary generates PDFs whose page size matches the label size. However, you may want to generate PDFs with a different page size and/or generate PDFs with multiple labels per page. If this is the case, you can add the X-Page-Size and X-Page-Layout HTTP headers to your request.

The X-Page-Size HTTP header tells Labelary to use a specific PDF page size. Valid values are Letter, A4, A5 and A6.

The X-Page-Layout HTTP header tells Labelary to lay out the labels on the PDF pages in a tabular format. The header value must be in the form <columns>x<rows>. For example, a value of 2x3 would generate a PDF file with 6 labels per page, arranged in 2 columns and 3 rows.

Note that these headers can only be used with PDF requests.

How many labels?

Sometimes your ZPL code may define multiple labels. If you want to know how many labels were generated by your ZPL, you can read the value of the X-Total-Count HTTP response header returned by Labelary. The value of this header will be accurate regardless of whether you requested that a single label be rendered (as in a PNG conversion) or you requested that all labels be rendered (as in some PDF conversions).

This header is available in both PNG and PDF responses.