Labelary Barcode API

"Few technologies have been more successful [than the barcode]... Many of the major companies that helped develop the most significant barcode standards no longer exist, but those standards are still going strong. Essentially the same objects that transmitted data to early computers in the 1970s are now trasmitting identification data stored in gigantic data centers. Some barcode technologies have changed, and some newer data standards for different types of barcodes have been developed. Nonetheless, the most iconic type of barcode that was used in the 1970s is still used today. There's something almost poetic about an infrastructural object remaining a steadfast constant as the systems it connects to became almost unrecognizable."

Jordan Frith, Barcode (Bloomsbury, 2023), 2-3.

1. Introduction

The Labelary Barcode API is a simple, easy-to-use RESTful API that makes it easy to add barcodes to any web-enabled system:

GET https://api.labelary.com/v1/barcodes?{parameters}

This API endpoint returns PNG images of barcodes which can be embedded into or manipulated by any system with internet access.

Example barcode

2. Parameters

The query string parameters define the barcode type, the barcode contents, the size of the barcode, and more.

Name Description Restrictions Default
key The API key to use. If none is provided, the returned image is watermarked. None None
type The type of barcode to generate. One of the symbology IDs below. code128
data The data to encode. Different barcodes have different data validation rules. Length: 1-1000 123456789012
mode The data mode used to provide the barcode data. standard, escaped or gs1 standard
xdim The module width (bar width), in pixels. Value: 1-10 2
ydim The module height (bar height), in pixels, for linear and stacked barcodes. Value: 1-500 Varies
qzh The horizontal "quiet zone", or empty space, to add to each side of the barcode. Value: 0-200 10
qzv The vertical "quiet zone", or empty space, to add above and below the barcode. Value: 0-200 10
rot The number of degrees to rotate the barcode clockwise. 0, 90, 180 or 270 0
fg The foreground color used to draw the barcode. Any color in RRGGBB hex format. 000000 (black)
bg The background color over which the barcode is drawn. Any color in RRGGBB hex format. FFFFFF (white)
hrt The position of the human-readable text. below, above or none below
fn The name of the font to use for the human-readable text. sans, serif, mono or ocrb sans
fs The size of the font to use for the human-readable text. Value: 4-40 12
ratio The wide-to-narrow bar width ratio, for barcodes with wide and narrow bars. Value: 2-3 3
check The number of check digits to add, for barcodes with customizable check digits. Varies Varies
ec The error correction level, for barcodes with customizable error correction. Varies Varies
size The barcode dimensions, for barcodes with rows and columns. Varies Auto
sap The structured append position, for barcodes which support data splitting. Varies None
sat The structured append total, for barcodes which support data splitting. Varies None
said The structured append file ID, for barcodes which support data splitting. Varies None
san The structured append file name, for barcodes which support data splitting. Varies None
mcm For maxicode barcodes, the mode to use. Value: 2-6 4
gph For ean13, ean8, upca and upce barcodes, the guard pattern height. Value: 0-20 5

3. Symbologies

The following symbologies, or barcode types, are available to be created:

NameIDTypeGS1ECIData Validation Rules
Aztec Codeaztec2D MatrixYesYes
Aztec Compactaztecc2D MatrixYesYes
Aztec Runerune2D MatrixNoNoValue: 0-255
CodabarcodabarLinearNoNoPattern: [A-D][0-9:\$\.\+\-\/]+[A-D]
Code 11code11LinearNoNoPattern: [0-9-]+
Code 128code128LinearYesNoPattern: [\u0000-\u00FF]+ (ISO-8859-1 text)
Code 39code39LinearNoNoPattern: [0-9A-Z$/+%\-\. \\]+
Code 39 Extendedcode39eLinearNoNoPattern: [\u0000-\u007F]+ (ASCII text)
Code 93code93LinearNoNoPattern: [\u0000-\u007F]+ (ASCII text)
Compact PDF417pdf417c2D StackedNoYes
Data Matrixdatamatrix2D MatrixYesYes
EAN-13ean13LinearNoNoPattern: [0-9]{12}(-[0-9]{2,5})? (with or without add-on)
EAN-8ean8LinearNoNoPattern: [0-9]{7}(-[0-9]{2,5})? (with or without add-on)
IATA 2 of 5iata25LinearNoNoPattern: [0-9]+
Industrial 2 of 5industrial25LinearNoNoPattern: [0-9]+
Interleaved 2 of 5interleaved25LinearNoNoPattern: [0-9]+
ITF-14itf14LinearNoNoPattern: [0-9]{13}
Matrix 2 of 5matrix25LinearNoNoPattern: [0-9]+
MaxiCodemaxicode2D MatrixNoYesVaries by mode, see below
MicroPDF417pdf417m2D StackedNoYes
Micro QR Codemicroqr2D MatrixNoNo
MSImsiLinearNoNoPattern: [0-9]+
PDF417pdf4172D StackedNoYes
PharmacodepharmacodeLinearNoNoValue: 3-131,070
Pharmacode Two-Trackpharmacode2LinearNoNoValue: 4-64,570,080
PZN8pzn8LinearNoNoPattern: [0-9]{7}
QR Codeqr2D MatrixYesYes
Swiss QR Codeswissqr2D MatrixNoNoSee specification
SSCC-18 / NVE-18sscc18LinearNoNoPattern: [0-9]{17}
TelepentelepenLinearNoNoPattern: [\u0000-\u007F]+ (ASCII text)
Telepen NumerictelepennLinearNoNoPattern: ([0-9][0-9]|[0-9]X)+
UPC-AupcaLinearNoNoPattern: [0-9]{11}(-[0-9]{2,5})? (with or without add-on)
UPC-EupceLinearNoNoPattern: [0-9]{7}(-[0-9]{2,5})? (with or without add-on)
UPN QRupnqr2D MatrixNoYesSee specification

4. Data Modes

There are three different ways to specify the data to encode, using three different mode values:

Standard

The first option is the standard data mode, which is the default. When you use this data mode, the data value is interpreted literally and is encoded directly as provided.

Example: https://api.labelary.com/v1/barcodes?mode=standard&data=ABCD (encodes the string "ABCD")

Escaped

The second option is the escaped data mode, which allows you to escape characters using ~UHHHH syntax, where HHHH is a four-digit hexadecimal number representing the Unicode code point of a character. When using this data mode, you can also use the escape sequence ~FNC1 to add FNC1 elements to the data.

Example: https://api.labelary.com/v1/barcodes?mode=escaped&data=c~U00F3digo (encodes the string "código")

Example: https://api.labelary.com/v1/barcodes?mode=escaped&data=~FNC12112345678~FNC113240101 (encodes the GS1 value "(21)12345678(13)240101")

GS1

The third option is the gs1 data mode, which allows you to use square brackets ([ ]) to indicate GS1 AIs (application identifiers). For example, you can create a GS1-128 barcode by combining the gs1 data mode with a code128 barcode, or you can create a GS1 Data Matrix by combining the gs1 data mode with a datamatrix barcode.

Example: https://api.labelary.com/v1/barcodes?mode=gs1&type=code128&data=[01]12345678901234 (encodes "(01)12345678901234" in a GS1-128 barcode)

Example: https://api.labelary.com/v1/barcodes?mode=gs1&type=datamatrix&data=[21]12345[13]240101 (encodes "(21)12345(13)240101" in a GS1 Data Matrix barcode)

5. Bar Width Ratios

The following symbologies allow bar width ratio customization with the ratio parameter:

SymbologyAvailable ValuesDefault Value
Codabar2-33
Code 112-33
Code 392-33
Code 39 Extended2-33
IATA 2 of 52-33
Industrial 2 of 52-33
Interleaved 2 of 52-33
ITF-142-33
Matrix 2 of 52-33

6. Check Digits

The following symbologies allow check digit customization with the check parameter:

SymbologyAvailable ValuesDefault Value
Code 111, 22
Code 390, 10
Code 39 Extended0, 10
Interleaved 2 of 50, 10
MSI0, 10, 1010, 11, 11100

7. Error Correction Levels

The following symbologies allow error correction level customization with the ec parameter:

SymbologyAvailable ValuesDefault Value
Aztec Code10, 23, 36, 50Auto
Aztec Compact10, 23, 36, 50Auto
Compact PDF4170-8Auto
Micro QR CodeL, M, QAuto
PDF4170-8Auto
QR CodeL, M, Q, HAuto

8. Rows and Columns

The following symbologies allow size customization with the size parameter:

SymbologyAvailable Values
Aztec Code19x19, 23x23, 27x27, 31x31, 37x37, 41x41, 45x45, 49x49, 53x53, 57x57, 61x61, 67x67, 71x71, 75x75, 79x79, 83x83, 87x87, 91x91, 95x95, 101x101, 105x105, 109x109, 113x113, 117x117, 121x121, 125x125, 131x131, 135x135, 139x139, 143x143, 147x147, 151x151
Aztec Compact15x15, 19x19, 23x23, 27x27
Compact PDF417Any combination of [1-30]x[3-90]
Data Matrix10x10, 12x12, 14x14, 16x16, 18x18, 20x20, 22x22, 24x24, 26x26, 32x32, 36x36, 40x40, 44x44, 48x48, 52x52, 64x64, 72x72, 80x80, 88x88, 96x96, 104x104, 120x120, 132x132, 144x144, 8x18, 8x32, 12x26, 12x36, 16x36, 16x48
MicroPDF4171x11, 1x14, 1x17, 1x20, 1x24, 1x28, 2x8, 2x11, 2x14, 2x17, 2x20, 2x23, 2x26, 3x6, 3x8, 3x10, 3x12, 3x15, 3x20, 3x26, 3x32, 3x38, 3x44, 4x4, 4x6, 4x8, 4x10, 4x12, 4x15, 4x20, 4x26, 4x32, 4x38, 4x44
Micro QR Code11x11, 13x13, 15x15, 17x17
PDF417Any combination of [1-30]x[3-90]
QR Code21x21, 25x25, 29x29, 33x33, 37x37, 41x41, 45x45, 49x49, 53x53, 57x57, 61x61, 65x65, 69x69, 73x73, 77x77, 81x81, 85x85, 89x89, 93x93, 97x97, 101x101, 105x105, 109x109, 113x113, 117x117, 121x121, 125x125, 129x129, 133x133, 137x137, 141x141, 145x145, 149x149, 153x153, 157x157, 161x161, 165x165, 169x169, 173x173, 177x177
Swiss QR Code41x41, 45x45, 49x49, 53x53, 57x57, 61x61, 65x65, 69x69, 73x73, 77x77, 81x81, 85x85, 89x89, 93x93, 97x97, 101x101, 105x105, 109x109, 113x113, 117x117, 121x121, 125x125, 129x129, 133x133, 137x137, 141x141, 145x145, 149x149, 153x153, 157x157, 161x161, 165x165, 169x169, 173x173, 177x177

9. Structured Append

Some symbologies allow splitting data across multiple symbols using the following Structured Append parameters:

  • The sat (structured append total) parameter indicates the total number of barcodes across which data is being split.
  • The sap (structured append position) parameter indicates the position of the current barcode within the sequence of barcodes (e.g. first, second, third, etc).
  • The said (structured append file ID) parameter provides a unique file identifier for the combined data (optional, not supported by all symbologies).
  • The san (structured append file name) parameter provides a unique file name for the combined data (optional, not supported by all symbologies).

These parameters may contain the following values:

SymbologyPosition (sap)Total (sat)File ID (said)File Name (san)
Aztec Code1-261-26Printable ASCII onlyN/A
Aztec Compact1-261-26Printable ASCII onlyN/A
Compact PDF4171-99,9991-99,9990-899Any text
Data Matrix1-161-161-64,516N/A
MaxiCode1-81-8N/AN/A
MicroPDF4171-99,9991-99,9990-899Any text
PDF4171-99,9991-99,9990-899Any text

10. MaxiCode Modes

MaxiCode barcodes have five different modes, configurable via the mcm parameter:

  • Mode 2: Structured carrier message (US domestic transportation)
  • Mode 3: Structured carrier message (international transportation)
  • Mode 4: Standard symbol
  • Mode 5: Full EEC (enhanced error correction)
  • Mode 6: Reader programming

The MaxiCode data validation pattern depends on the MaxiCode mode used. For MaxiCode mode 2 (US transportation), the validation pattern is:

\[\)>\u001E01\u001D[0-9]{2}[0-9]{9}\u001D[0-9]{3}\u001D[0-9]{3}\u001D.+

For MaxiCode mode 3 (international transportation), the validation pattern is:

\[\)>\u001E01\u001D[0-9]{2}[0-9A-Z ]{6}\u001D[0-9]{3}\u001D[0-9]{3}\u001D.+

For MaxiCode modes 4, 5 and 6, any data string is valid.

Note that MaxiCode modes 2 and 3 both expect the postal code, ISO country code, and service code to follow the standard prefix, in that order. In mode 2, the postal code is a 9-digit ZIP code. In mode 3, the postal code is a 6-character alphanumeric code.

11. Error Handling

If any invalid parameter values are provided to the API, the system will return an HTTP 200 (OK) response containing a PNG image with an error message instead of a barcode.

This allows easy error diagnosis and resolution in reports and other low-code / no-code environments which may not provide easy access to other HTTP response information.

This is an example error image generated by the API when an unknown parameter named aaa is provided:

Example error

For users who have access to more advanced HTTP response information, error messages are also returned in the X-Warnings HTTP response header:

X-Warnings: Parameter 'aaa' is unknown; please check for typos in the parameter name

12. Support

If you have any issues or questions that are not answered in the API documentation, you can reach our support team via email at support@labelary.com.

The support response time SLA for licensed users is one business day. Support for non-licensed users is on a best-effort basis only.

If you have any questions about the current status of the API, or recent availability statistics, you can visit the Labelary status page.

13. Plans and Pricing

Get started for free, with no signup required, and upgrade as your needs grow.

You can choose whether you'd like to be billed monthly or annually. Customers who choose to commit for a full year receive the 12th month free.

If you don't see a plan that fits your specific requirements, just email us and we'll see if we can create a custom plan for you.

MonthlyYearly Barcode
Trial
Barcode
Basic
Barcode
Plus
Barcode
Business
Free $44/month $90/month $228/month
WatermarkYesNoNoNo
SupportNoneBasicPriorityPremium
Availability SLANone99%99.9%99.9%
Release ChannelBetaStableStableStable
Maximum Data Retention60 daysNeverNeverNever
Maximum Barcodes per Day1001,00010,00050,000
Maximum Image Size (pixels)200,000200,000500,0001,000,000
API KeyNoneProvided via emailProvided via emailProvided via email
API Serverapi.labelary.comProvided via emailProvided via emailProvided via email
Sign Up Sign Up Sign Up

14. Barcode Generator Web UI

The Labelary Barcode Generator is a web-based tool for creating barcodes. It uses the Labelary Barcode API internally, and is a great way to explore the API in a visual and intuitive way. You can experiment with different parameter combinations, spot check individual barcodes, or explore and learn about different types of barcodes.

Labelary Barcode Generator

15. No-Code / Low-Code Examples

The Labelary Barcode API is designed to be usable from a wide variety of platforms with little-to-no coding required.

See below for integration details for curl, HTML, Markdown, Excel, Google Sheets, Google Docs, Make, and Zapier.

15.1. curl

The following command uses the curl command line tool to create a Code 128 barcode image:

curl -G https://api.labelary.com/v1/barcodes --data "key=YOUR-API-KEY" --data "type=code128" --data-urlencode "data=12345678" > barcode.png

15.2. HTML

You can easily embed barcode images directly in HTML pages:

<img src="https://api.labelary.com/v1/barcodes?key=YOUR-API-KEY&type=code128&data=12345678" alt="Barcode">

15.3. Markdown

You can also add barcode images to Markdown pages:

![Barcode](https://api.labelary.com/v1/barcodes?key=YOUR-API-KEY&type=code128&data=12345678)

15.4. Excel

You can use the Excel IMAGE function to add barcode images in Excel for Microsoft 365 and Excel for the Web.

For example, assuming that your barcode data is in cell A2, you can use the following formula to add a Data Matrix barcode image to the current cell:

=IMAGE(CONCAT("https://api.labelary.com/v1/barcodes?key=YOUR-API-KEY&type=datamatrix&data=",A2),"Barcode",0)

15.5. Google Sheets

Google Sheets also has an IMAGE function that can be used to add barcode images to spreadsheets.

For example, assuming that your barcode data is in cell A2, you can use the following formula to add a QR Code image to the current cell:

=IMAGE(CONCAT("https://api.labelary.com/v1/barcodes?key=YOUR-API-KEY&type=qr&data=",ENCODEURL(A2)),3)

15.6. Google Docs

Barcode images can be added to a Google Docs document by choosing the Insert menu, selecting the Image option, and then selecting the By URL menu item. Enter the Labelary barcode API URL in the text box, and click Insert Image.

Google Docs screenshot

15.7. Make

Make is a cloud-based process automation software suite. It allows you to design automated workflows visually, without writing any code. The following sample Make "scenario" watches a #barcode Slack channel for new messages, and automatically responds to any messages sent to the channel with a barcode image of the user's message:

Make screenshot

15.8. Zapier

Zapier is a workflow automation tool which allows you to connect your applications using custom workflows, or "zaps", without any custom software development. The following sample "zap" watches a Google Sheets worksheet for new rows, and when a new row is added it creates a new barcode image using the data in the new row, saving the barcode image to Google Drive.

Zapier screenshot

16. Coding Examples

The code snippets and examples below are intended to help you start consuming the Labelary Barcode API quickly, regardless of your client-side technology stack.

See below for PHP, JavaScript, Node.js, Python, Ruby, Java and C# code samples.

16.1. PHP Example

The following PHP template generates a webpage with an embedded Data Matrix barcode image:

<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="utf-8">
        <title>PHP Example</title>
    </head>
    <body>
    <?php
        $params = array('key' => 'YOUR-API-KEY', 'type' => 'datamatrix', 'data' => '12345678');
        $querystring = http_build_query($params); // always encode the barcode data
        $barcode = file_get_contents('https://api.labelary.com/v1/barcodes?' . $querystring);
        echo '<img src="data:image/png;base64,' . base64_encode($barcode) . '" alt="Barcode">' . PHP_EOL;
    ?>
    </body>
</html>

16.2. JavaScript Example

The following webpage uses JavaScript to update a QR Code image according to the data provided by the user:

<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="utf-8">
        <title>JavaScript Example</title>
    </head>
    <body>
        <input type="text" id="input">
        <input type="button" onclick="update()" value="Update">
        <br><br>
        <img id="barcode" alt="Barcode Image" src="data:,">
        <script>
            function update() {
                const input = document.getElementById('input');
                const barcode = document.getElementById('barcode');
                const data = encodeURIComponent(input.value); // always encode the barcode data
                barcode.src = 'https://api.labelary.com/v1/barcodes?key=YOUR-API-KEY&type=qr&data=' + data;
            }
        </script>
    </body>
</html>

16.3. Node.js Example

The following Node example uses the fetch API to create a Data Matrix barcode image:

const fs = require('fs');

const data = encodeURIComponent('12345678'); // always encode the barcode data

fetch('https://api.labelary.com/v1/barcodes?key=YOUR-API-KEY&type=datamatrix&data=' + data)
  .then(response => {
    if (response.ok) {
      const warnings = response.headers.get('X-Warnings');
      if (warnings) {
        console.error(warnings); // API input error
      } else {
        const name = 'barcode.png';
        const opts = { flag: 'w' };
        response.arrayBuffer().then(body => fs.appendFileSync(name, Buffer.from(body), opts)); // success
      }
    } else {
      response.text().then(msg => console.error(msg)); // API fatal error
    }
  })
  .catch(error => {
    console.error(error); // network error
  });

16.4. Python Example

The following Python example uses the Requests library to create a Code 39 barcode image:

import requests

params = { 'key': 'YOUR-API-KEY', 'type': 'code39', 'data': '12345678' }
response = requests.get('https://api.labelary.com/v1/barcodes', params = params) # params encoded automatically

if response.status_code == 200:
    if 'X-Warnings' in response.headers:
        warnings = response.headers['X-Warnings']
        print(warnings) # API input error
    else:
        with open('barcode.png', 'wb') as png:
            png.write(response.content) # success
else:
    print(response.text) # API fatal error

16.5. Ruby Example

The following Ruby example creates a Code 128 barcode image:

require 'net/http'

uri = URI 'https://api.labelary.com/v1/barcodes'
params = { :key => 'YOUR-API-KEY', :type => 'code128', :data => '12345678' }
uri.query = URI.encode_www_form(params) # always encode the barcode data
response = Net::HTTP.get_response(uri)

case response
when Net::HTTPSuccess then
    warnings = response['X-Warnings']
    if warnings.nil?
        File.open 'barcode.png', 'wb' do |f|
            f.write response.body # success
        end
    else
        puts warnings # API input error
    end
else
    puts response.body # API fatal error
end

16.6. Java Example

The following Java example uses the Java 11 HttpClient API to create a Data Matrix barcode image:

var data = URLEncoder.encode("12345678", StandardCharsets.UTF_8); // always encode the barcode data
var uri = URI.create("https://api.labelary.com/v1/barcodes?key=YOUR-API-KEY&type=datamatrix&data=" + data);
var request = HttpRequest.newBuilder(uri).build();
var client = HttpClient.newHttpClient();
var response = client.send(request, BodyHandlers.ofByteArray());
var body = response.body();

if (response.statusCode() == 200) {
    var warnings = response.headers().firstValue("X-Warnings").orElse("");
    if (warnings.isEmpty()) {
        Files.write(Path.of("barcode.png"), body); // success
    } else {
        System.out.println(warnings); // API input error
    }
} else {
    var message = new String(body, StandardCharsets.UTF_8); // API fatal error
    System.out.println(message);
}

16.7. C# Example

The following C# example uses the HttpClient API to create a PDF417 barcode image:

using System.Web;

var query = HttpUtility.ParseQueryString(string.Empty); // params encoded automatically
query["key"] = "YOUR-API-KEY";
query["type"] = "pdf417";
query["data"] = "12345678";

var url = "https://api.labelary.com/v1/barcodes?" + query.ToString();
var client = new HttpClient();
var response = await client.GetAsync(url);
if (response.IsSuccessStatusCode) {
    if (response.Headers.Contains("X-Warnings")) {
        var warnings = response.Headers.GetValues("X-Warnings").First();
        Console.WriteLine(warnings); // API input error
    } else {
        using (var stream = await response.Content.ReadAsStreamAsync()) {
            using (var file = new FileStream("barcode.png", FileMode.Create)) {
                await stream.CopyToAsync(file); // success
            }
        }
    }
} else {
    var message = await response.Content.ReadAsStringAsync();
    Console.WriteLine(message); // API fatal error
}