Barcode parameters

The "Barcode" web service can be used to generate and recognize barcodes in PDF documents.

 

The "<add>" element is used to add barcodes, while the "<detect>" element is used to read existing barcodes.

 

add operation

 

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<operation xmlns="http://schema.webpdf.de/1.0/operation">
<barcode>
  <add>
    <aztec value="https://www.webpdf.de/"
          pages=""
          charset="utf-8"
          errorCorrection="7"
          layers="0"
          margin="0"
          rotation="0">
      <position
              x="0"
              y="0"
              width="0"
              height="0"
              coordinates="user"
              metrics="mm"/>
    </aztec>
  </add>
</barcode>
</operation>

 

{
"barcode": {
  "add":{
    "aztec":{
      "value":"https://www.webpdf.de/",
      "pages":"",
      "charset":"utf-8",
      "errorCorrection":7,
      "layers":0,
      "margin":0,
      "rotation":0,
      "position": {
        "x": 0,
        "y": 0,
        "width": 0,
        "height": 0,
        "coordinates": "user",
        "metrics": "mm"
       }
     }
   }
 }
}

 

add element

 

Used to add a new barcode to the document.

 

<add>
<aztec value="https://www.webpdf.de/"
        pages=""
        charset="utf-8"
        errorCorrection="7"
        layers="0"
        margin="0"
        rotation="0">
  <position ... />
</aztec>
</add>

"add":{
"aztec":{
    "value":"https://www.webpdf.de/",
    "pages":"",
    "charset":"utf-8",
    "errorCorrection":7,
    "layers":0,
    "margin":0,
    "rotation":0,
    "position": {...}
  }
}

 

One or more sub-elements that define barcodes can be entered in the "<add>" element. The following elements are available:

 

aztec

codabar

code128

code39

datamatrix

ean13

ean8

itf

pdf417

qrcode

upca

 

All barcode elements have a number of basic attributes in common. These attributes are described below.

 

value (default: "")

Contains the value that should be encoded in the barcode. Depending on the selected barcode format, there may be specific criteria for the data structure. For a description, please refer to "Barcodes"

 

pages (default: "")

The page range for generating barcodes. Individual pages or a range of pages can be defined here. If the text is empty, the entire file will be exported (e.g.: "1-10" or "1,2,5-10")

 

charset (default: "utf-8")

 Used to specify the character set in which the barcode contents should be stored.

 

rotation (default: 0)

 Used to specify the barcode’s rotation in 90-degree increments. When there is a value that falls under a full 90-degree increment, the next higher increment will be automatically selected.

 

margin (default: 0)

 Used to specify the width of the empty frame that should be generated around the barcode.

 

 

In addition to the common basic attributes, there are also a number of settings that apply to individual barcodes only. These settings are described below.

 

aztec element

 

<aztec value="https://www.webpdf.de/"
      ...
      errorCorrection="7"
      layers="0">

       ...
</aztec>

"aztec":{
   ...
  "errorCorrection":7,
  "layers":0,

   ...
}

 

errorCorrection (default: 7)

Used to adjust the error correction level for generated Aztec Codes. The higher the level, the more error-resistant the barcode, ensuring that damaged codes will still be readable. A percentage value of one to one hundred can be entered.

 

layers (default: 0)

Used to specify the number of layers that the generated Aztec Code should use. The higher the number, the larger the resulting barcode and its capacity.

"-4" to "-1" = Compact Aztec Code with a minimum capacity of 13 digits or 12 letters and an area of 15 x 15 pixels.

"0" = Standard Aztec Code that will be optimized in order to use the smallest possible of layers for the value that is being encoded.

"1" to "32" = Standard Aztec Code with a maximum capacity of 3832 digits or 3067 letters and an area of 151 x 151 pixels.

 

datamatrix element

 

<datamatrix value="https://www.webpdf.de/"
      ...
      errorCorrection="2"
      shape="default">
       ...
</datamatrix>

"datamatrix":{
   ...
  "errorCorrection":2,
  "shape":"default",

   ...
}

 

errorCorrection (default: 2)

Used to adjust the error correction level for generated Data Matrix codes. The higher the level, the more error-resistant the barcode, ensuring that damaged codes will still be readable. A level of 1 to 8 can be specified.

 

shape (default: "default")

 Can be used to force a specific shape for generated Data Matrix codes.

default = Select an appropriate shape.

rectangle = Force a rectangular shape.

square = Force a square shape.

 

qrcode element

 

<qrcode value="https://www.webpdf.de/"
      ...
      errorCorrection="h"
      ...
</qrcode>

"qrcode":{
   ...
  "errorCorrection":"h",

   ...
}

 

errorCorrection (default: "l")

Used to adjust the error correction level for generated QR codes. The higher the level, the more error-resistant the barcode, ensuring that damaged codes will still be readable.

l = Low

m = Medium

q = Quartile

h = High

 

pdf417 element

 

<pdf417 value="https://www.webpdf.de/"
    ...
    errorCorrection="2"
    compact="true"
    compactionMode="auto"
    shape="default"
    dataCodewordsMax=""
    dataCodewordsMin=""
    symbolsPerCodewordMax=""
    symbolsPerCodewordMin=""
    ...
</pdf417>

"pdf417":{
  ...
  errorCorrection:2,
  compact:true,
  compactionMode:"auto",
  shape:"default",
  dataCodewordsMax:"",
  dataCodewordsMin:"",
  symbolsPerCodewordMax:"",
  symbolsPerCodewordMin:"",

  ...
}

 

errorCorrection (default: 2)

Used to adjust the error correction level for generated PDF417 codes. The higher the level, the more error-resistant the barcode, ensuring that damaged codes will still be readable. A level of 1 to 8 can be specified.

 

compact (default: false)

If this value is set to "true," the contents of all generated PDF417 barcodes will be compressed using the encoding selected with the "compactionMode" attribute.

 

compactionMode (default: "auto")

If PDF417 barcode compression has been enabled with the "compact" attribute, the encoding selected here for the compression of generated PDF417 barcodes will be used.

auto = Try to determine the best encoding method automatically.

byte = Select a byte encoding method in which every 5 codewords represent 6 bytes.

numeric = Select a numeric encoding method in which a group of 15 codewords represents up to 44 decimal numbers.

text = Select a text encoding method in which each codeword represents up to 2 letters.

 

shape (default: "default")

 Can be used to force a specific shape for generated PDF417 barcodes.

default = Select an appropriate shape.

rectangle = Force a rectangular shape.

square = Force a square shape.

 

dataCodewordMax

Used to specify the maximum number of codewords allowed in a single PDF417 barcode row.

 

dataCodeWordMin

Used to specify the minimum number of codewords allowed in a single PDF417 barcode row.

 

symbolsPerCodewordMax

Used to specify the maximum number of code symbols that are allowed to be in a single codeword in the PDF417 barcode.

 

symbolsPerCodewordMin

Used to specify the minimum number of code symbols that are allowed to be in a single codeword in the PDF417 barcode.

 

 

position element

 

This element is used to define the barcode’s position and size. Please make sure that this area is large enough for the selected barcode. Certain barcodes require a minimum area in order to be displayed. If the area is not large enough, an error may occur. In addition, keep in mind that the selected area will not always be filled out 100% with the barcode if the latter needs to conform to specific proportion and display ratios.

 

<position
      x="0"
      y="0"
      width="0"
      height="0"
      coordinates="user"
      metrics="mm"/>

"position": {
  "x": 0,
  "y": 0,
  "width": 0,
  "height": 0,
  "coordinates": "user",
  "metrics": "mm"
}

 

x (default: 0)

The barcode’s X-axis position.

 

y (default: 0)

The barcode’s Y-axis position

 

width (default: 0)

The barcode’s width

 

height (default: 0)

The barcode’s height

 

coordinates (default: "user")

Used to specify the coordinate system for the arguments.

user = User coordinate system (origin at top left)

pdf = PDF coordinate system (origin at bottom right)

 

metrics (default:"mm")

Unit for the X-axis/Y-axis position and barcode height and width arguments:

mm = Millimetres

px = Pixels

 

 

detect operation

 

This operation is used to define the barcode recognition parameters. The system will attempt to find barcodes inside the area defined with "<scanArea>". The recognition process itself is controlled with "<selection>".

 

hint

Make sure that the defined scanning area (e.g., only a subsection of a page) and the number of pages is not too big, as the recognition process is extremely compute-intensive and accordingly may take a very long time if you fail to take this into account.

 

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<operation xmlns="http://schema.webpdf.de/1.0/operation">
<barcode>
  <detect inputFormat="pdf" outputFormat="xml">
    <selection formats=""
              charset="utf-8"
              pages=""
              allowedLengths=""
              barcode39CheckDigit="true"
              codabarStartEndDigits="true"
              gs1="true"
              pureBarcode="true"
              resolution="200"
              tryHarder="true"
              upcEanExtensions="">
      <scanArea x="0"
                y="0"
                width="100"
                height="100"
                coordinates="user"
                metrics="mm"/>
    </selection>
  </detect>
</barcode>
</operation>

{
"barcode": {
  "detect":{
    "inputFormat":"pdf",
    "outputFormat":"xml",
    "selection":{
      "formats":"",
      "charset":"utf-8",
      "pages":"",
      "allowedLengths":"",
      "barcode39CheckDigit":true,
      "codabarStartEndDigits":true,
      "gs1":true,
      "pureBarcode":true,
      "resolution":200,
      "tryHarder":true,
      "upcEanExtensions":""
     },
    "scanArea":{
      "x": 0,
      "y": 0,
      "width": 100,
      "height": 100,
      "coordinates": "user",
      "metrics": "mm"
     }
   }
 }
}

 

detect element

 

Used to define the input and output formats for the recognition process.

 

<detect inputFormat="pdf" outputFormat="xml">
     ...
</detect>

"detect":{
  "inputFormat":"pdf",
  "outputFormat":"xml",
  ...
}

 

inputFormat (default: "pdf")

Used to select the format of the file with the contents that will be scanned for barcodes.

pdf = PDF document

img = Image document (JPG, PNG, TIF)

 

outputFormat (default: "json")

Used to select the format in which the recognition results should be returned.

json = JSON

xml = XML

 

selection element

 

This section is used to control the recognition process and configure settings that apply only to specific barcode types.

 

<selection formats=""
    charset="utf-8"
    pages=""
    allowedLengths=""
    barcode39CheckDigit="true"
    codabarStartEndDigits="true"
    gs1="true"
    pureBarcode="true"
    resolution="200"
    tryHarder="true"
    upcEanExtensions="">
  <scanArea ... />
</selection>

"selection":{
"formats":"",
"charset":"utf-8",
"pages":"",
"allowedLengths":"",
"barcode39CheckDigit":true,
"codabarStartEndDigits":true,
"gs1":true,
"pureBarcode":true,
"resolution":200,
"tryHarder":true,
"upcEanExtensions":""

 ...
},

 

formats

Used to define the list of barcodes (comma-separated) that should be searched for. There must be at least one barcode format here; otherwise, no search will be run. The names are the same as those used in "<add>", i.e., the following are the barcode names available:

qrcode

aztec

codabar

code128

code39

datamatrix

ean13

ean8

itf

pdf417

upca

 

charset (default: "utf-8")

Used to specify the character set in which the barcode contents are stored.

 

pages (default: "")

The page range within which barcodes should be scanned. Individual pages or a range of pages can be defined here. If the text is empty, the entire file will be exported (e.g.: "1-10" or "1,2,5-10")

 

allowedLengths (default: "")

If this value is set, it will limit the allowed lengths for encoded values. In other words, barcodes with a length that is not listed will be ignored. (Example: "13,8,25")

 

barcode39CheckDigit (default: false)

If this value is set to "true", the system will assume that all recognized Code 39 barcodes contain a correct check digit.

 

codabarStartEndDigits (default: false)

If this value is set to "true", the start and stop symbols of recognized Codabar barcodes will be read instead of removed during recognition.

 

gs1 (default: false)

If this value is set to "true", the system will assume that all recognized barcodes are GS1-compliant barcodes, and the way all processes behave and work will be adjusted accordingly (for instance, the way in which the FNC1 character is handled for Code 128)

 

pureBarcode (default: false)

If this value is set to "true", the system will assume that the source document being scanned (limited by "<scanArea>") does not contain any elements other than the barcode. This option can speed up the recognition process significantly. If, however, this option is enabled and there are elements other than a barcode, recognition may fail completely.

 

resolution (default: 200)

Used to select the resolution for the recognition operation. Depending on the barcode’s format and quality, higher or lower values may yield better results (in any case, higher values will slow down processing).

 

tryHarder (default: true)

If this value is set to "true", more computing time will be invested in order to guarantee successful recognition. For example, the system will also scan for barcodes along the vertical axis.

 

upcEanExtensions (default: "")

If this value is set, it will limit the allowed lengths for encoded EAN and UPC Extensions. In other words, barcodes with an Extension length that is not listed will be ignored. (Example: "2,5")

 

scanArea element

 

This element is used to define the area that will be scanned for barcodes. This area must always be specified. The more exactly you can specify the area, the faster the recognition process and the lower the number of false positives will be.

 

<scanArea x="0"
        y="0"
        width="100"
        height="100"
        coordinates="user"
        metrics="mm"/>

"scanArea":{
  "x": 0,
  "y": 0,
  "width": 100,
  "height": 100,
  "coordinates": "user",
  "metrics": "mm"
}  

 

x (default: 0)

The area’s X-axis position.

 

y (default: 0)

The area’s Y-axis position.

 

width (default: 0)

The area’s width. A value of 0 will select the entire available page area in the X-axis.

 

height (default: 0)

The area’s height. A value of 0 will select the entire available page area in the Y-axis.

 

coordinates (default: "user")

Used to specify the coordinate system for the arguments.

user = User coordinate system (origin at top left)

pdf = PDF coordinate system (origin at bottom right)

 

metrics (default:"mm")

Unit for the X-axis/Y-axis position and area height and width arguments:

mm = Millimetres

px = Pixels