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.

2. Parameters

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

Show parameters for: All Symbologies Aztec Code Aztec Compact Aztec Rune Codabar Code 11 Code 128 Code 39 Code 39 Extended Code 93 Compact PDF417 Data Matrix EAN-13 EAN-8 IATA 2 of 5 Industrial 2 of 5 Interleaved 2 of 5 ITF-14 Matrix 2 of 5 MaxiCode MicroPDF417 Micro QR Code MSI PDF417 Pharmacode Pharmacode Two-Track PZN8 QR Code Swiss QR Code SSCC-18 / NVE-18 Telepen Telepen Numeric UPC-A UPC-E UPN QR

3. Symbologies

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

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:

6. Check Digits

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

7. Error Correction Levels

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

8. Rows and Columns

The following symbologies allow size customization with the size parameter:

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:

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.

The default mode is mode 4 (standard symbol).

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:

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 12^th 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.

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.

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:


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.

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:

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.

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
}