McAPI - Barcode API Ruby

Ruby sample code to create barcodes with the McAPI Barcode REST API service. The sample uses Ruby 2.6 but the code will also work with Ruby 3. The samples use the packages uri, net/http and openssl which should all be available with a standard Ruby installation. If not, simply install them using GEM.

Requirements: A free RapidAPI account. Replace YOUR_API_KEY in the code snippets below with your own api key.

All samples below work with the free tier of the API, see RapidAPI McAPI Barcode Listing for available plans.

See the overview page for a reference that lists all available parameters and error codes.

Create a Barcode using Ruby

Shown is the creation of a Code 128 (code type: 7) with Ruby. All relevant parameters are in the body of the request. The barcode will encode the text "123456". The module width is set to 0.5mm, the height is set to 20mm, the size of the human readable text under the barcode is set to 10 points. The code will be created and returned as a base64 encoded PDF.

The source code:

# Ruby
  
require 'uri'
require 'net/http'
require 'openssl'

url = URI("https://mcapi-barcode.p.rapidapi.com/")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Post.new(url)
request["content-type"] = 'application/json'
request["x-rapidapi-key"] = 'YOUR_API_KEY'
request["x-rapidapi-host"] = 'mcapi-barcode.p.rapidapi.com'
request.body = "{
    \"data\": \"123456\",
    \"type\": 7,
    \"moduleWidth\": 0.5,
    \"moduleHeight\": 20,
    \"hrSize\": 10,
    \"format\": \"pdf\"
}"

response = http.request(request)

The data will be delivered as JSON in response.read_body e.g.:

{
  "service":"McAPI Barcode Generator, https://mcapi.io",
  "version":"V1",
  "format":"pdf",
  "code":"data:application/pdf;base64,JVBE ... Cg=="
}

See further below for a snippet that shows how to parse the response.

McAPI Barcode API - Sample barcode with Ruby

The returned code from the Ruby request:

Image of McAPI Barcode API Sample Barcode Ruby

Creating retail barcodes EAN, ISBN, UPC with Ruby

The introductory sample above created a Code 128 barcode. Code 128 has many applications, mostly in warehousing and logistics. In the following Ruby snippet we show how to create EAN and UPC barcodes which are used in retail.

Let's create an EAN 13 code. First step is to set the code type. The reference section lists all available code types; for EAN 13, we have to set the type-parameter to "1". With Code 128, we set the size of the code by specifing values for moduleWidth and moduleHeight. Retail codes are standardized, with the standard specifying the permitted sizes (so called SC sizes). With the Barcode API, the size of retail barcodes is determined through the size-parameter, with "2" being the 100% size. Here's the body block for creating an EAN 13 encoding "401234567890", again returning a PDF:

# Ruby

...

request.body = "{
    \"data\": \"401234567890\",
    \"type\": 1,
    \"size\": 2,
    \"format\": \"pdf\", 
}"

...

Here's the resulting EAN 13:

Image of McAPI Barcode API EAN 13 Barcode Ruby

As an aside, the reference section also specifies the expected data for each barcode symbology. EAN 13 encodes twelve digits plus check digit (hence the name). As such you'll have to specify twelve or thirteen digits, less than twelve or more than thirteen will result in an error, likewise if the submitted data contains letters. The API will always recalculate the check digit for retail codes to make sure that a valid symbol is created; for the given data the EAN 13 check digit is "1" which will be appended automatically to the data.

Incidentally, the greater sign (">") right of the barcode is the so called light margin indicator. The indicator tells the graphics designer not to put other graphical elements too close to the code. The indicator can be switched off by setting the lmi-parameter to "false".

Shortened EAN 13 (Ruby)

As you can see, EAN codes can get quite large, with small boxes, wrappers or packages the code might not fit into the available space. Per the standard, it's permitted to reduce the height of the code to some degree as long as the height doesn't get lower than 10mm. The Barcode API supports a special truncate-parameter for retail codes. The parameter is percentage based, e.g. "50" will create a code with half height.

Sample body block:

# Ruby

...

request.body = "{
    \"data\": \"401234567890\",
    \"type\": 1,
    \"size\": 2,
    \"truncate\": 50,
    \"format\": \"pdf\",
}"

...

Here's the resulting EAN 13 with half height:

Image of McAPI Barcode API EAN 13 Truncated Barcode Ruby

EAN 13 with additional text (Ruby)

A very useful feature of the Barcode API is the support for supplemental text that can be put above and below the barcode. This can be used for item descriptions, package size, pricing, best before dates, weight etc.

The parameters over, under and suppSize control any additional text. The following body block will put the text "Paperclips" above the code, the text "$2.99" below the code and set the size of the supplemental text to 8pt.:

# Ruby

...

request.body = "{
    \"data\": \"401234567890\",
    \"type\": 1,
    \"size\": 2,
    \"truncate\": 50,
    \"over\": \"Paperclips\",
    \"under\": \"$2.99\",
    \"suppSize\": 8,    
    \"format\": \"pdf\",
}"

...

The resulting EAN 13 with additional text:

Image of McAPI Barcode API EAN 13 Price Best before Barcode Ruby

Note: Additional text must be from the ASCII character set, Unicode is not supported.

Creating an EAN barcode without text (Ruby)

Sometimes you will only want the actual barcode without any text at all; that's possible too: Simply specify the hrText-parameter as "false", like so:

# Ruby
  
...

request.body = "{
    \"data\": \"401234567890\",
    \"type\": 1,
    \"size\": 2,
    \"truncate\": 50,
    \"hrText\" : \"false\",
    \"format\": \"pdf\",
}"

...

The resulting EAN 13 barcode without text:

Image of McAPI Barcode API EAN 13 No text Barcode Ruby

Creating 2D matrix barcodes with Ruby

The Barcode API supports the most common 2D barcode symbologies: Datamatrix, Datamatrix GS1, PDF417, QR and Aztec. Creating those codes in Ruby is no different from ordinary, linear barcodes we saw above; the only aspect to consider is using the moduleWidth-parameter to control the size of the code. With the exception of PDF417, dots are square, i.e. moduleWidth equals moduleHeight. With PDF417, the dots are created with a 3:1 ratio, i.e. moduleHeight equals 3 * moduleWidth.

The following body block will create a Datamatrix code (type = "16") with a dot size of 1x1mm²:

# Ruby

...

request.body = "{
    \"data\": \"1234567890\",
    \"type\": 16,
    \"moduleWidth\": 1,
    \"format\": \"pdf\",
}"

...

The Datamatrix code from the snippet above:

Image of McAPI Barcode API Datamatrix 2D Barcode Ruby

2D barcodes are always created without text as the encoded data is typically too much to be displayed. Use the over and under parameters to put small amounts of text (no more than 30 characters, ASCII only) next to the code.

Create QR codes with Ruby

The Barcode API supports the creation of QR codes that can contain plain text, URLs, email addresses, phone numbers and SMS numbers. Our QR implementation is fully Unicode-compatible. Ruby can natively handle UTF-8 characters or strings (like german "umlauts", e.g. "ÄÖÜ", or non-latin script, e.g. "日本語") so there's no special treatment required for that kind of data.

Specify content as follows:

  • Plain text (max. 2,000 chars): "123456abcdefÄÖÜ日本語"
  • URL: Specify data param like so: "https://example.com"
  • Email: Specify data param like so: "mailto:info@example.com"
  • Phone no: Specify data param like so: "tel:+18005551234"
  • SMS: Specify data param like so: "smsto:44044"

Sample body block to create a QR code with the URL "https://mcapi.io":

# Ruby

...

request.body = "{
    \"data\": \"https://mcapi.io\",
    \"type\": 19,
    \"moduleWidth\": 1,
    \"format\": \"pdf\",
}"

...

The resulting QR code:

Image of McAPI Barcode API QR URL Barcode Ruby

The header-parameter - writing barcodes to a file (Ruby)

With all supported formats, the barcode is returned as a base64 encoded string. Per default, this string is preceded by a header that describes the media type (or MIME) of the string.

Sample body block for a QR code, to be returned as a PNG:

# Ruby
  
...

request.body = "{
    \"data\": \"https://mcapi.io\",
    \"type\": 19,
    \"moduleWidth\": 1,
    \"format\": \"png\",
}"

...

The response will look like this:

{
  "service":"McAPI Barcode Generator, https://mcapi.io",
  "version":"V1",
  "format":"png",
  "code":"data:image/png;base64,iVBOR ... QmCC"
}

After parsing the result with a JSON parser you can directly set the "code"-string as the src property of an img tag, like so:

# Ruby

require json

...

if response.code == "200"
  # In production code you would wrap the parser in begin/rescue/end
  barcode = JSON.parse(response.read_body)["code"]
  puts('<img src="' + barcode + '"/>')
else
  puts("Error")
end

...

The MIME header will make sure that the image data is interpreted correctly by the browser. However, when writing the image data to a file, including the header would result in a corrupt file. To create a code without the header, set the header-parameter to "false", like so:

# Ruby
  
...

request.body = "{
    \"data\": \"https://mcapi.io\",
    \"type\": 19,
    \"moduleWidth\": 1,
    \"header\": \"false\",
    \"format\": \"png\",
}"

...

The returned code without header:

{
  "service":"McAPI Barcode Generator, https://mcapi.io",
  "version":"V1",
  "format":"png",
  "code":"iVBOR ... QmCC"
}

Now, all we have to do is decode the base64 string to get the image data. Shown here as a complete example that creates a QR code as a PNG and then writes the barcode to a file:

# Ruby

require 'uri'
require 'net/http'
require 'openssl'
require 'json'
require 'base64'

url = URI("https://mcapi-barcode.p.rapidapi.com/")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Post.new(url)
request["content-type"] = 'application/json'
request["x-rapidapi-key"] = 'YOUR_API_KEY'
request["x-rapidapi-host"] = 'mcapi-barcode.p.rapidapi.com'
request.body = "{
    \"data\": \"https://mcapi.io\",
    \"type\": 19,
    \"moduleWidth\": 1,
    \"header\": \"false\",
    \"format\": \"png\",     
}"

response = http.request(request)
if response.code == "200"
  # In production code you would wrap the parser in begin/rescue/end
  barcode = JSON.parse(response.read_body)["code"]
  png = Base64.decode64(barcode)
  File.open("barcode.png", "wb") do |f|
    f.write(png)
  end
else
  puts("Error")
end

Back to McAPI Barcode API main page.