EVRYTHNG offers an Identifier Recognition service through the REST API. Developers can use this resource to identify barcodes in images, and any linked products or Thngs linked to those codes. A common use of this capability is when a web app is used by consumers to scan a QR code on the packaging of their purchase in order to learn more information about the product, such as provenance, traceability history, access rewards, and so on.
Any Application and Operator API key can POST
an image, and if a product/Thng redirection or barcode matches the image, the service returns information about the matches made. This includes any redirection information set up for the resource that matched the image recognition query. In the case that a barcode is found but it does not link to a Thng or product in scope of the authenticating API key, the raw decoded data is returned in case it can still be of use.
WalkthroughFor a complete walkthrough of the process of utilizing product recognition, read Real-time Web Product Scanning.
API Status
General Availability:
/scan/identifications
tn.gg/redirections/:shortId/ir
Beta:
/scan/identifications
when method=ocr
/scan/identifications
when method=digimarc
/scan/identifications
tn.gg/redirections/:shortId/ir
Beta:
/scan/identifications
when method=ocr
/scan/identifications
when method=digimarc
Enabling Recognition
To enable recognition of a specific type of barcode, include the appropriate product identifier as an item in the identifiers
field in the Thng or product to be recognised when scanned. If a scanned image contains the barcode listed in these identifiers, that resource is returned.
This can be done through the REST API, or via the Dashboard. The value of the key should be the numerical value encoded within the barcode itself as a string. For example a barcode containing 96385074
as an EAN 8 barcode will match the following Thng:
Alternatively, if the scanned image is a Thng or product redirection QR code, you can also use the encoded URL as the value
field, where applicable. QR codes generated when adding a redirection for a given Thng or product will also be matched independently of the identifiers
listed through their redirection's shortId
.
value
field, where applicable. QR codes generated when adding a redirection for a given Thng or product will also be matched independently of the identifiers
listed through their redirection's shortId
.Performing a Scan or Identification
Scanning an image is performed by making a POST
request to /scan/identifications
through the API, or using the scan()
method in the scanthng.js SDK. The filter
query parameter specified dictates which types of codes are searched for or recognition methods are attempted on the supplied image payload.
Similarly, a GET
request to the same resource will attempt to find any products or Thngs visible to the authenticating Application or Operator API Key with a code containing the value
query parameter value. For example, a QR code with tn.gg
redirection to a product would match a value=https://tn.gg/yyZZ1nAh
query parameter value.
See Identify from an Image or Read an Identifier's Product or Thng for example requests.
Filter Format
The filter
query parameter can contain the following items:
-
method
- String The scanning method to use. -
type
- String The type of identifier to identify.
You can optionally also include the following parameters in the URL query string:
-
perPage
- Integer Specify how many items to return per page of results. -
debug
- Boolean Set totrue
to view extra information used to measure performance.
ImportantThe
filter
text must be URL encoded, similar to other Platform filters.
The different types of methods and identifier types are shown in the table below:
Matching and Response
When a code type matching the filter
specified is found in the image, the Identifier Recognition API looks for a Thng/product that is visible to the API key that performed the call (i.e.: in the same scope).
The response is an array containing metadata and a set of matching results, if any were found. If there were no results, or an incompatible combination of method
and type
were specified, an empty array will be returned. If the scan was performed on behalf of a user, their object will also be included, allowing extra functionality such as Scan actions. An example is shown below:
Data Fields
-
results
- Object array Array of identification results, containing the matching Thng/product and any redirections associated with it. -
meta
- Object Object containing metadata about the identification operation.-
meta.method
- String Themethod
used to identify the product/Thng. -
meta.score
- Number Confidence score of the results for their
method
, or100
for one or more matches for the othermethod
values, else0
if no Thngs or products were found. -
meta.value
- String The actual value encoded within the identifier. Can be used with aGET
request to retrieve the associated Thng/product. -
meta.type
- String Thetype
used to identify the Thng/product.
-
Payload Sources
The /scan/identifications
endpoint accepts JPG and PNG images as a file upload or Base64-encoded image data as a string.
File Upload
You can upload a file either from a file browser or a direct camera capture on mobile devices. The scanthng.js
library includes this functionality as part of its API. When the scan()
method is invoked, the device-specific native dialog for choosing a file or capturing from a camera is shown to the user. See below for examples.
Base64 Data
As an alternative to uploading a file through evrythng.js, Base64 image data may also be submitted in the request body. The image must be encoded in a string containing the MIME type header before the actual image data (i.e.: "data:{content-type},...{Base64 data}..."
) and be nested inside a JSON object with the image
key. A truncated example is shown below:
{
"image": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAS..."
}
Example File Uploads
File Upload
Base64 Data
Identify from an Image
ImportantThe
filter
text must be URL encoded, similar to other Platform filters.
When a request is made to the /scan/identifications
endpoint with the POST
method, the image is analysed according to the filter
query string provided, and one or more matches to products/Thngs are produced if they list the matching identifiers
values.
Read an Identifier's Product or Thng
If a value
has already been extracted from an image with a decoding library, or via the POST /scan/identifications
endpoint, you can read the associated product or Thng with a GET
request containing a filter specifying the type
of the identifier.
NoteThe
type
parameter must be specified with the submittedvalue
for the identification to succeed. For example,type: 'qr_code'
when identifying a URLvalue: 'https://tn.gg/yyZZ1nAh'
from a QR code.
Create an IR Reference Image
Upload a local file as a reference image for a given redirection short ID.
Read all IR Reference Images
Read all uploaded reference images for a given short ID.
Delete an IR Reference Image
Remove a previously uploaded reference image by id
.
Scan Actions
A scans
action created upon a successful recognition generates valuable contextual data which can be used for business rules/decision making and data insights analysis. For example: geolocation, browser and device type, anonymous user ID.
Creating a scans
action can done using the result returned by scan()
with the evrythng.js SDK. An example is shown below:
With this option enabled, you will receive a lot more useful data items, shown in the example below. Most notable are the addition of the location
, and createdBy...
items, which can be used for analysis and decision making when aggregated across a large number of scans.
Redirections
Once an identifier has been recognized, the results can be used to redirect the user to a pre-set destination according to any redirections attached to the product/Thng associated with the result. For example:
Error Codes
The table below details the error codes that may be returned by the Identifier Recognition API:
Known Issues
-
Denying access to location in Firefox, IE11, and Edge browsers can cause issues with
scanthng.js
. Make sure to guide users to always accept the request for location data. -
Using a web app or page in Safari Incognito mode can cause issues with
scanthng.js
. Apps should display a message instructing users to not use Safari Incognito mode.