Skip to content

Online Barcode API

Jump to bottom
metafloor edited this page Jun 16, 2016 · 9 revisions

The bwipjs online API is hosted by OpenShift using a node.js application. You can use this API to dynamically generate barcode images from anywhere on the web. The returned image is in PNG format.

The online API is implemented by the node-bwipjs module provided in the main repository, so if you are running a node server, you can implement the same functionality on your local systems.

The API is accessed using the URL: http://api-bwipjs.rhcloud.com/

Only HTTP GET requests with parameters specified in the URL query string are valid.
The only required parameters are the barcode type and value to encode, using the bcid and text parameters:

http://api-bwipjs.rhcloud.com/?bcid=code128&text=1234567890

The bcid= must follow immediately after the ? question mark.

The list of supported barcode types (encoders) is available at Supported Barcode Symbologies.

The remaining parameters can be broken into two groups, bwip-js parameters and BWIPP parameters.

bwip-js Parameters

  • scaleX : The x-axis scaling factor. Must be an integer > 0. Default is 2.

  • scaleY : The y-axis scaling factor. Must be an integer > 0. Default is scaleX.

  • scale : Sets both the x-axis and y-axis scaling factors. Must be an integer > 0.

  • rotate : Allows rotating the image to one of the four orthogonal orientations:

    • N : Normal (not rotated). This is the default.
    • R : Clockwise 90 degree rotation.
    • L : Counter-clockwise 90 degree rotation.
    • I : Inverted 180 degree rotation.

  • monochrome : Sets the image text to render in monochrome. The default is 256-level gray-scale anti-aliased.

For example, to render a code128 barcode at 3x scale with inverted orientation and displaying the text (a BWIPP-specific option):

http://api-bwipjs.rhcloud.com/?bcid=code128&text=AB1234567890&scale=3&rotate=I&includetext

BWIPP Parameters

BWIPP has two types of options, boolean and valued. Boolean parameters take no value; their presence in the URL specifies enabled/true. Valued parameters must be followed by an equals-sign (no spaces) and the value. The value string must be URL-encoded.

The following is an example of rendering a code128 barcode using the BWIPP parsefnc boolean option and specifying alternate text to appear below the barcode:

http://api-bwipjs.rhcloud.com/?bcid=code128&text=%5EFNC1011234567890&parsefnc&alttext=%2801%291234567890

The %5E at the start of the text= parameter is the ^ ASCII caret, URL-encoded. BWIPP uses ^ to indicate control words and other values unique to each type of barcode. The alttext, in human-readable form is (01)1234567890 where the parentheses were URL-encoded. In JavaScript, use the encodeURIComponent() global method to encode the value string of any parameter.

You will need to consult the BWIPP documentation to understand what parameters are available for each barcode type.

How to use

From within an HTML document, you can use the API anywhere you can specify an image URL. For example, as a CSS background-image URL or as the src in an <img> tag. For example:

<img alt="Barcoded value 1234567890"
     src="http://api-bwipjs.rhcloud.com/?bcid=code128&text=1234567890&includetext">

When used from a server, you must initiate an HTTP GET request. The HTTP response will be either status 200 with Content-Type: image/png or status 4XX with Content-Type: text/plain when an error occurs. The returned text will give an indication of what went wrong. Your client should also be prepared to handle HTTP 302 and 307 redirects.

Clone this wiki locally