Identifier Recognition (legacy)

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.

❗Walkthrough

For 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

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.

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 to true to view extra information used to measure performance.

❗Important

The 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 The method used to identify the product/Thng.

  • meta.score - Number Confidence score of the results for the ir method, or 100 for one or more matches for the other method values, else 0 if no Thngs or products were found.

  • meta.value - String The actual value encoded within the identifier. Can be used with a GET request to retrieve the associated Thng/product.

  • meta.type - String The type 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

❗Important

The 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.

❗Note

The type parameter must be specified with the submitted value for the identification to succeed. For example, type: 'qr_code' when identifying a URL value: '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.