Barcode Recognition

Detects and decodes 1D and 2D barcodes in an image that you provide.

The Barcode Recognition API detects barcodes from an image. For each recognized barcode, it returns the type, the decoded barcode value, and the coordinates of the corners of a box that surrounds the barcode.

The Barcode Recognition API recognizes barcodes with the following formats:

  • EAN-13 (includes ISBN)
    Note: The EAN-13 barcode type is a superset of the UPC-A type, so the API returns the EAN type, rather than the UPC value. To find the UPC value, remove the leading 0 from the EAN value.
  • EAN-8
  • EAN-2 (includes ISBN-2)
  • EAN-5 (includes ISBN-5)
  • Codabar
  • Code-128
  • Code-39
  • Code-93
  • Datalogic 2/5
  • Data Matrix
  • IATA 2/5
  • Industrial 2/5
  • Matrix 2/5
  • Patch Code (or Patch)
  • PDF417
  • UCC/EAN-128 (or GS1-128)
  • UPC-A
  • UPC-E
  • QR Code

For more information about barcode formats, refer to www.gs1.org/barcodes/technical/bar_code_types

For a list of file formats that you can use for images, see Supported Image Formats.

Barcode recognition is most reliable for approximately horizontally or vertically aligned barcodes (up to 20° rotation), although in some cases detection works for all alignments up to 45°. The image must also be high contrast, and preferably two-tone (black and white).

Synchronous
https://api.idolondemand.com/1/api/sync/recognizebarcodes/v1
Asynchronous
https://api.idolondemand.com/1/api/async/recognizebarcodes/v1
Authentication

This API requires an authentication token to be supplied in the following parameter:

ParameterDescription
apikeyThe API key to use to authenticate the API request.
Input Source

This API accepts a single input source that can be supplied using one of the following parameters:

ParameterDescription
fileA file containing the image to process. Multi part POST only.
referenceAn IDOL OnDemand reference obtained from either the Expand Container or Store Object API. The corresponding image is passed to the API.
urlA publicly accessible HTTP URL from which the image can be retrieved.
Parameters

In addition to the above input source, this API accepts the following parameters:

NameTypeDescription
barcode_type
array <barcode_type> The type of barcode you are trying to recognize. Default value: all1d,qr
barcode_orientation
enum <barcode_orientation> Information about the barcode orientation in the images that you are submitting. Default value: any
All parameters for this API are optional.
Enumeration Types

This API's parameters use the enumerations described below:

barcode_type
The type of barcode you are trying to recognize.
all All
All supported barcode types.
all1d All supported 1D types
All 1-Dimensional barcode types.
all2d All supported 2D types
All 2-Dimensional barcode types.
codabar Codabar (1D)
See http://en.wikipedia.org/wiki/Codabar
code-128 Code-128 (1D)
See http://en.wikipedia.org/wiki/Code_128
code-39 Code-39 (1D)
See http://en.wikipedia.org/wiki/Code_39
code-93 Code-93 (1D)
See http://en.wikipedia.org/wiki/Code_93
datalogic 2/5 Datalogic 2/5 (1D)
data matrix Data Matrix (2D)
http://en.wikipedia.org/wiki/Data_Matrix
ean-128 EAN-128 (1D)
See http://en.wikipedia.org/wiki/GS1-128
ean-13 EAN-13 (1D)
See http://en.wikipedia.org/wiki/International_Article_Number_%28EAN%29
ean-2 EAN-2 (1D)
See http://http://en.wikipedia.org/wiki/EAN_2
ean-5 EAN-5 (1D)
See http://en.wikipedia.org/wiki/EAN_5
ean-8 EAN-8 (1D)
See http://en.wikipedia.org/wiki/EAN-8
iata 2/5 IATA 2/5 (1D)
industrial 2/5 Industrial 2/5 (1D)
See http://en.wikipedia.org/wiki/Two-out-of-five_code
matrix 2/5 Matrix 2/5 (1D)
See http://www.n-barcode.com/en/shurui/m-25.html
patch code Patch Code (1D)
pdf417 PDF417 (2D)
See http://en.wikipedia.org/wiki/PDF417
qr QR Code (2D)
See http://en.wikipedia.org/wiki/QR_code
ucc UCC (1D)
See http://en.wikipedia.org/wiki/GS1-128
upc-a UPC-A (1D)
See http://en.wikipedia.org/wiki/Universal_Product_Code
upc-e UPC-E (1D)
See http://en.wikipedia.org/wiki/Universal_Product_Code#UPC-E
barcode_orientation
Information about the barcode orientation in the images that you are submitting.
upright Upright
Your barcodes are always in an upright orientation.
any Any
Your barcodes can be in any orientation.

This API returns a JSON response that is described by the model below. This single model is presented both as an easy to read abstract definition and as the formal JSON schema.

Model
This is an abstract definition of the response that describes each of the properties that might be returned.
Barcode Recognition Response {
barcode (array[Barcode]) Details of a recognized barcode in the image.
}
Barcode {
text (string) The decoded barcode value.
barcode_type (enum<Barcode_type>) The type of barcode recognized.
left (integer) The position of the left edge of the barcode in the image.
top (integer) The position of the top edge of the barcode in the image.
width (integer) The width of the barcode in the image.
height (integer) The height of the barcode in the image.
additional_information (Additional_information, optional)
}
enum<Barcode_type> {
'codabar' See http://en.wikipedia.org/wiki/Codabar
'code-128' See http://en.wikipedia.org/wiki/Code_128
'code-39' See http://en.wikipedia.org/wiki/Code_39
'code-93' See http://en.wikipedia.org/wiki/Code_93
'datalogic 2/5'
'data matrix' http://en.wikipedia.org/wiki/Data_Matrix
'ean-128' See http://en.wikipedia.org/wiki/GS1-128
'ean-13' See http://en.wikipedia.org/wiki/International_Article_Number_%28EAN%29
'ean-2' See http://http://en.wikipedia.org/wiki/EAN_2
'ean-5' See http://en.wikipedia.org/wiki/EAN_5
'ean-8' See http://en.wikipedia.org/wiki/EAN-8
'iata 2/5'
'industrial 2/5' See http://en.wikipedia.org/wiki/Two-out-of-five_code
'matrix 2/5' See http://www.n-barcode.com/en/shurui/m-25.html
'patch code'
'pdf417' See http://en.wikipedia.org/wiki/PDF417
'qr' See http://en.wikipedia.org/wiki/QR_code
'ucc' See http://en.wikipedia.org/wiki/GS1-128
'upc-a' See http://en.wikipedia.org/wiki/Universal_Product_Code
'upc-e' See http://en.wikipedia.org/wiki/Universal_Product_Code#UPC-E
}
Additional_information {
country (string, optional) The GS1 country code of the barcode (EAN-13 and UPC-A barcodes only).
}
Model Schema
This is a JSON schema that describes the syntax of the response. See json-schema.org for a complete reference.
{
    "type": "object",
    "properties": {
        "barcode": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "text": {
                        "type": "string"
                    },
                    "barcode_type": {
                        "enum": [
                            "codabar",
                            "code-128",
                            "code-39",
                            "code-93",
                            "datalogic 2/5",
                            "data matrix",
                            "ean-128",
                            "ean-13",
                            "ean-2",
                            "ean-5",
                            "ean-8",
                            "iata 2/5",
                            "industrial 2/5",
                            "matrix 2/5",
                            "patch code",
                            "pdf417",
                            "qr",
                            "ucc",
                            "upc-a",
                            "upc-e"
                        ]
                    },
                    "left": {
                        "type": "integer"
                    },
                    "top": {
                        "type": "integer"
                    },
                    "width": {
                        "type": "integer"
                    },
                    "height": {
                        "type": "integer"
                    },
                    "additional_information": {
                        "type": "object",
                        "properties": {
                            "country": {
                                "type": "string"
                            }
                        }
                    }
                },
                "required": [
                    "text",
                    "barcode_type",
                    "left",
                    "top",
                    "width",
                    "height"
                ]
            }
        }
    },
    "required": [
        "barcode"
    ]
}
https://api.idolondemand.com/1/api/sync/recognizebarcodes/v1
/developer/api/api-example/1/api/sync/recognizebarcodes/v1
Examples
See this API for yourself - select one of our examples below.
Input Source
ParameterValue
file
reference
url
Parameters
NameTypeValue
barcode_type
array (Default: all1d,qr)
barcode_orientation
enum

ASync – Response An error occurred making the API request
Response Code:
Response Body

	

Making API Request…
Checking result of job

To try this API with your own data and use it in your own applications, you need an API Key. You can create an API Key from your account page - API Keys.

Output Refresh An error occurred making the API request View the raw output View Input
Rendered RawHtml Response
Result Display
Response Code:
Response Body:

		
Make this call with curl
curl


If you would like to provide us with more information then please use the box below:

We will use your submission to help improve our product.