Documentation

Reader.DataSymbol.com API


Getting Started

This tutorial will show you how to use the Reader.DataSymbol.com API to decode a file with barcode. There are only three short steps involved:
  1. Obtain an API Key
  2. Start Barcode Decoding Job
  3. Get Barcode Decoding Result

1. Obtain an API key.

Every request to the Reader.DataSymbol.com API must include a API Key, so that we can identify you. Once you have signed up for an account, you can get your API Key.

2. Start Barcode Decoding Job

To convert a file with Reader.DataSymbol.com, you need to send a request to the jobs endpoint. Note that this is a multi-part request. The first part contains binary data (your image file) while the other part contains typical POST data: a key-value pair.

2.1 Start Job Request

  • Shell
  • Node.js
  • C#
  • PHP

curl -k https://reader.datasymbol.com/api/job \
 -X POST \
 -F "key=0CWWQhS9wo1f7AwlvVoA" \
 -F "source_file=@/home/mike/Desktop/Images/linear-4.jpg" \
 -F "target=barcode-reader" \
 -F "out_format=xml" \
 -F "lnum=2"
	

var request = require('request');
var fs = require('fs');

var req = request.post({url:"https://reader.datasymbol.com/api/job"}, function (err, resp, body) {
  if (err) {
        console.error('Unable to start conversion job', err);
  } else {
    //console.log(JSON.parse(body));
    var respJSON = JSON.parse(body);
    console.log(respJSON.error.code + ": " + respJSON.error.message);
    console.log("Job ID: " + respJSON.job.id);
  }
});

var form = req.form();
form.append("target", "barcode-reader");
form.append("key", "0CWWQhS9wo1f7AwlvVoA");
form.append("out_format", "json");
form.append("source_file", fs.createReadStream('/home/mike/Desktop/Images/linear-4.jpg'));
	

const uint ST_DATAMATRIX            = 0x10000000;
const uint ST_PDF417                = 0x20000000;
//...

const string urlJob = "https://reader.datasymbol.com/api/job";
const string apiKey = "0CWWQhS9wo1f7AwlvVoA";
const string fileName = "c:\\tmp\\linear-4.jpg";
barcodeTypes = ST_PDF417|ST_DATAMATRIX;

//send job
string xmlString = Upload(apiKey, urlJob, fileName, barcodeTypes).Result;
//xml result
XmlDocument doc = new XmlDocument();
doc.LoadXml(xmlString);

static async Task Upload(string apiKey, string url, string sourceFile, uint barcodeTypes)
{
	using (HttpClientHandler handler = new HttpClientHandler())
	using (HttpClient client = new HttpClient(handler))
	{
		var request = new MultipartFormDataContent();

		request.Add(new StringContent(apiKey), "key");
		request.Add(new StringContent("barcode-reader"), "target");
		request.Add(new StringContent("xml"), "out_format");
		//request.Add(new StringContent("5"), "lnum");
		request.Add(new StringContent(barcodeTypes.ToString()), "types");
		request.Add(new StreamContent(File.OpenRead(sourceFile)), "source_file", new FileInfo(sourceFile).Name);

		using (HttpResponseMessage response = await client.PostAsync(url, request).ConfigureAwait(false))
		using (HttpContent content = response.Content)
		{
			string data = await content.ReadAsStringAsync();
			return data;
		}
	}
}
	

<?php
	$apiUrl = 'https://reader.datasymbol.com/api/job';
	$imagePath = '/home/mike/Desktop/Images/linear-4.jpg';
	$apiKey = '0CWWQhS9wo1f7AwlvVoA';

	$ch = curl_init();
	curl_setopt($ch, CURLOPT_URL, $apiUrl);
	curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
	curl_setopt($ch, CURLOPT_POST, true);
	curl_setopt($ch, CURLOPT_HTTPHEADER, array("Content-type: multipart/form-data"));

	$post_array = array(
		'key'=>$apiKey,
		'target'=>'barcode-reader',
		'source_file'=>curl_file_create($imagePath),
		//'source_file'=>"@$imagePath",
		//'out_format'=>'json',
		'lnum'=>7,
		'types'=>(0x00000008|0x00000001),  //find only EAN-13 and Code-128
	);

	curl_setopt($ch, CURLOPT_POSTFIELDS, $post_array);
	$data = curl_exec($ch);

	$header_str = curl_getinfo($ch, CURLINFO_CONTENT_TYPE);
	curl_close($ch);

	header("Content-type: " . $header_str);
	echo $data;
?>
	

2.2 Start Job Response

The response contains the status of the new job ("error" node) and confirms the some parameters included in your request.

  • XML
  • JSON

<BarcodeReader version='1.1'>
	<error code='1001'>Info. in queue</error>
	<job id='216288' key='0CWWQhS9wo1f7AwlvVoA' queue='1' start_time='2016-12-05-10-09-49' stop_time='' />
	<source_file name='linear-4.jpg' />
</BarcodeReader>
	

{
  version: '1.1',
  error: { code: 1001, message: 'Info. in queue' },
  job: 
   { id: 216288,
     key: '0CWWQhS9wo1f7AwlvVoA',
     queue: 1,
     start_time: '2016-12-05-10-15-54',
     stop_time: '' },
  source_file: { name: 'linear-4.jpg' }
}
	

Reader.DataSymbol.com is now decoding your file.

3. Get Barcode Decoding Result

Before you can access the result, you should check to see whether your job has finished successfully, by sending a GET or POST request. In this request, you’ll need to use the Job ID (above 216288) returned by Reader.DataSymbol.com when you created your job and your API Key. Once your job has completed successfully, the response "error code" will "0".

3.1 Get Result Request

  • Shell
  • Node.js
  • C#
  • PHP

curl -k https://reader.datasymbol.com/api/job \
 -X POST \
 -F "id=216288" \
 -F "key=0CWWQhS9wo1f7AwlvVoA"
	

var request = require('request');

apiKey = "0CWWQhS9wo1f7AwlvVoA";
jobID = 216288;

var req = request.get({url:"https://reader.datasymbol.com/api/"+apiKey+"/"+jobID+"/json"}, function (err, resp, body) {
  if (err) {
        console.error('Unable to start conversion job', err);
  } else {
    var respJSON = JSON.parse(body);
    console.log(respJSON);
    if (respJSON.error.code == 0) {
      for (i=0; i < respJSON.result.barcodes.length; ++i) {
        console.log(respJSON.result.barcodes[i].text);
      }
    }
  }
});
	

int jobID = 216288;
string endpoint = urlBase + apiKey + "/" + jobID.ToString() + "/xml";
string xmlString = Query(apiKey, endpoint).Result;

XmlDocument doc = new XmlDocument();
doc.LoadXml(xmlString);

        static async Task Query(string key, string url)
        {
            using (HttpClientHandler handler = new HttpClientHandler())
            using (HttpClient client = new HttpClient())
            using (HttpResponseMessage response = await client.GetAsync(url).ConfigureAwait(continueOnCapturedContext: false))
            using (HttpContent content = response.Content)
            {
                string data = await content.ReadAsStringAsync();
                return data;
            }
        }
	

<?php
	$apiBase = 'https://reader.datasymbol.com/api/';
	$apiKey = '0CWWQhS9wo1f7AwlvVoA';
	$jobID = 216288;

	$xml = file_get_contents($apiBase . $apiKey. "/" . $jobID . "/xml");

	header('Content-Type: text/xml');
	print $xml;
?>
	

3.2 Get Result Response

  • XML
  • JSON

<BarcodeReader version='1.1'>
	<error code='0'>Ok</error>
	<job id='216288' key='0CWWQhS9wo1f7AwlvVoA' queue='-1' start_time='2016-12-05-10-09-49' stop_time='2016-12-05-10-09-49' />
	<source_file name='linear-4.jpg' />
	<credit_cost cost='5' credit='1108925' />
	<result>
		<barcodes qty='4'>
			<barcode type='4' page='1'>
				<text><![CDATA[BarcodeTools.comt]]></text>
				<data></data>
				<coordinates x1='370' y1='356' x2='937' y2='327' x3='365' y3='234' x4='932' y4='205' />
			</barcode>
			<barcode type='4' page='1'>
				<text><![CDATA[9781779100290]]></text>
				<data></data>
				<coordinates x1='145' y1='622' x2='403' y2='722' x3='218' y3='433' x4='476' y4='533' />
			</barcode>
		</barcodes>
	</result>
</BarcodeReader>
	

{
  "version":"1.1",
  "error":{"code":0, "message":"Ok"},
  "job":{"id":216288, "key":"0CWWQhS9wo1f7AwlvVoA", "queue":-1, "start_time":"2016-12-05-10-09-49", "stop_time":"2016-12-05-10-09-49"},
  "source_file":{"name":"linear-4.jpg"},
  "credit_cost":{"cost":5, "credit":1108920},
  "result":
    {
      "barcodes":[
        {"type":1, "page":1, "text":"BarcodeTools.comt", "data":"", "coordinates":[{"x":370, "y":356}, {"x":937, "y":327}, {"x":365, "y":234}, {"x":932, "y":205}]},
        {"type":8, "page":1, "text":"9781779100290", "data":"", "coordinates":[{"x":145, "y":622}, {"x":403, "y":722}, {"x":218, "y":433}, {"x":476, "y":533}]}
      ]
    }
}
	


If decoded barcode contains only ASCII characters then you can use "text" node. If "text" node is empty then you should to use "data" node that is base64 encoded.

4. Reference

4.1 Error/Info codes

Error CodeDescription
0Ok
1incorrect key
2cannot connect with DB
3cannot find the key
4key expired
5not enought key credit
6no source file
7file size exceed limit
8cannot move uploaded file
9upload error
10invalid file type
11cannot add job
12cannot get job
13error
14job id not found
15incorrect job id
16job id or key not found
17file size exceeds server limit
18wrong target
19cannot find result
20incorrect file ID
21cannot find file ID
22cannot open file
23cannot read file
24product/plan not found
101processing. error
102processing. cannot load config
103processing. cannot parse config
104processing. cannot load source file
201decoding. cannot set barcode decoder params
202decoding. error during decoding
203decoding. cannot parse params
1001info. in queue
1002info. processing



4.2 Parameters

ParameterDescription
Service Parameters
keyyour API Key
idJob ID
out_formatRequired format of a response.
Possible values: "xml", "json"
Default value: "xml"
del_resultDelete result after "Get Result Response".
Possible values: "yes", "no"
Default value: "no"
pagePage for decoding (if multipage file).
Default value: 0 (all pages)
Barcode Decoder Parameters
typestypes of barcodes should be decoded
frameTimeTime to decode 1 frame in milliseconds.
Default value: "0"(unlimited)
inversewhat barcodes should be decoded (darks on light or lights on dark).
Possible values: 0-dark, 1-light, 2-both
Default value: "0"
lnumLinear. how many barcodes should be decoded
Default value: "1"
lshowidLinear. add symbology ID to the barcode text
Default value: "0"
lverifycheckLinear. verify the optional check digit in barcodes where this check digit is optional
Default value: "0"
lshowcheckLinear. show the check
Default value: "1"
lshowststLinear. show the start/stop characters
Default value: "0"
lcode39extLinear. decode Code 39 as Code 39 Extended
Default value: "0"
lupceupcaLinear. convert a UPC-E barcode to UPC-A
Default value: "0"
lspeedLinear. Decoding speed
Possible values: 0-Normal, 1-Fast, 2-Slow
Default value: "0"
lverifyLinear. improves reliability linear barcode reading.
Default value: "0"
pdf417numPDF417. how many barcodes should be decoded
Default value: "1"
pdf417speedPDF417. Decoding speed
Possible values: 0-Normal, 1-Fast, 2-Slow
Default value: "0"
pdf417symidPDF417. add symbology ID to the barcode text
Default value: "0"
pdf417microPDF417. Finds Micro PDF417 barcodes.
Default value: "0"
pdf417supporteciPDF417. support ECI (Extended Channel Interpretation).
Default value: "0"
pdf417robustPDF417. Activates the robust PDF417 decoder mode. This property can help to decode high distorted PDF417 barcodes.
Default value: "0"
dmnumDataMatrix. how many barcodes should be decoded
Default value: "1"
dmspeedDataMatrix. Decoding speed
Possible values: 0-Normal, 1-Fast, 2-Slow
Default value: "0"
dmsymidDataMatrix. add symbology ID to the barcode text
Default value: "0"
dmsupporteciDataMatrix. support ECI (Extended Channel Interpretation).
Default value: "0"
dminverseDataMatrix. find inverse DataMatrix
Default value: "0"
qrnumQRCode. how many barcodes should be decoded
Default value: "1"
qrspeedQRCode. Decoding speed
Possible values: 0-Normal, 1-Fast, 2-Slow
Default value: "0"
qrsymidQRCode. add symbology ID to the barcode text
Default value: "0"
qrmicroQRCode. Finds Micro QRCode barcodes.
Default value: "0"
aznumAztecCode. how many barcodes should be decoded
Default value: "1"
azspeedAztecCode. Decoding speed
Possible values: 0-Normal, 1-Fast, 2-Slow
Default value: "0"
azsymidAztecCode. add symbology ID to the barcode text
Default value: "0"



4.3 Barcode Types

Value (hexadecimal)Barcode Type
0x00000001Code 128
0x00000002Code 39
0x00000004Interleaved 2/5
0x00000008EAN-13
0x00000010EAN-8
0x00000020Codabar
0x00000040Code 11
0x00000080UPC-A
0x00000100UPC-E
0x00000200Industrial 2/5
0x00000400Code 93
0x00000800DataBar omnidirectional, DataBar Truncated
0x00001000DataBar limited
0x00002000DataBar stacked
0x00004000DataBar Expanded
0x00008000DataBar Expanded stacked
0x01000000unrecognized linear
0x02000000unrecognized PDF417
0x04000000unrecognized DataMatrix
0x08000000unrecognized QRCode
0x00100000unrecognized AztecCode
0x10000000DataMatrix
0x20000000PDF417
0x40000000QRCode
0x80000000AztecCode


Copyright © 1999-2017, RKD Software & RKD System Inc., All rights reserved.
All trademarks mentioned are the property of their respective owners.