Introduction

For a product to be recognized, it must be mapped to a Tiliter Archetype.

Once you've created your products, the next step is to map them to Tiliter Archetypes. This must be done before the Recognition API recognise anything.

What are Archetypes?

Tiliter Archetypes are internal representations of the output from the Tiliter recognition model. When an image is sent to the API for recognition, the model internally returns Tiliter Archetypes, which are then translated into products using the mapping.

Creating the links between your products and the Tiliter Archetypes is called mapping.

For example, your product might be called "Large Banana", and it would need to be mapped to the Tiliter Archetype called "Banana - Cavendish".

Which Archetypes are supported?

The list of archetypes is provided at the List Archetypes endpoint. Here's how to call the endpoint using a Unix-like command-line interface:

curl --request GET --url https://recognition.services.tiliter.com/archetypes/ --header 'accept: application/json' --header 'tiliter-api-key: YOUR_API_KEY'

Fundamentals

For most products, mapping is very straightforward. It involves identifying which Tiliter product best represents the retailer’s product.

A minority of products generally take up most of the time, and this usually occurs when naming conventions differ between regions or stores.

Creating a product mapping is described in Create Product Mapping.

Here's how to map a product to an archetype using a Unix-like command-line interface:

curl --request POST --url https://recognition.services.tiliter.com/product_mappings/ --header 'accept: application/json' --header 'content-type: application/json' --header 'tiliter-api-key: YOUR_API_KEY' --data ' { "product_id": "PRODUCT1", "archetype_id": "43d1fe3d-0248-1182-851b-5e6a23f264f2" } '

The expected response to this is:

{ "product_id": "PRODUCT1", "archetype_id": "43d1fe3d-0248-1182-851b-5e6a23f264f2" }

Each product you wish to recognise needs to be mapped to at least one Tiliter Archetype.

It is possible to map to multiple Tiliter Archetypes, and more complex mappings are possible.

Worked example

In this section, we will walk through the process of mapping the example product catalogue from the Creating Products section.

Mapping is done by hand and it is generally easier to first create a spreadsheet and identify what you will map, and then after that's complete, register each mapping with the Tiliter API.

Export the product catalogue to a spreadsheet

To start, export the product catalogue into a spreadsheet format. This allows you to view each product on a single line, and will make the mapping easier.

In our worked example, the exported product catalogue looks like this:

Add columns for the Tiliter Archetypes

Next we will add two additional columns: Tiliter Archetype ID and Tiliter Archetype Name. These will be filled in by hand in the next step

Match products with Tiliter Archetype Names

The best way to start mapping is to retrieve a list of Tiliter Archetypes, and then review them and identify the products that have the most clear straightforward link to a Tiliter Archetype based on the Tiliter Archetype Name.

You can bring up a list of Tiliter Archetypes using /archetypes/ endpoint. This is described over at List Archetypes.

Here's how you can get the list of Archetypes using a Unix-like command-line interface:

curl --request GET --url https://recognition.services.tiliter.com/archetypes/ --header 'accept: application/json' --header 'tiliter-api-key: YOUR_API_KEY'

After reviewing the Tiliter Archetype Names, we found matches for the first three products in our catalogue:

• Large Banana -> Banana Cavendish
• Loose Limes -> Lime
• Portobello mushrooms -> Mushroom Portobello

Inputting the Tiliter Archetype ID and Name gives us the following mapping spreadsheet:

Match products with Alternate Names

Next, we will review the Alternate Names of the Tiliter Archetypes.

Alternate Names are names that produce may be referred to in different regions. Here are some examples of regional naming differences:

Alternate names can be found in the list of Tiliter Archetypes we retrieved earlier.

In the following excerpt, we learn that Tiliter Archetype Capsicum Red is also known as Red Bell Pepper

Updating our mapping spreadsheet gives us:

Use Tiliter's reference photos for assistance

Upon request, Tiliter can provide reference photos of all Tiliter Archetypes.

Reviewing these will generally reveal additional mappings that can be made.

In our example, we find that both Opal Apple and Yello Apple both closely match to Apple Yellow. Note that this is a somewhat contrived example, since it would be unusual to stock two extremely similar products like this.

Adding these in gives us:

Note that both Opal Apple and Yello Apple both map to the same Tiliter Archetype. This means that when the Recognition API internally recognizes Apple Yellow it will return the products Opal Apple and Yello Apple.

Map special cases

And finally

Our goal is to identify the appropriate Tiliter Archetype to map to, for each product in the product catalogue.

Tiliter has a large variety of internationally sold products. If your product is sold internationally, it is likely to exist. However, due to regional naming differences, it may be referred to using a different name.

Create each mapping in the API

The Create Product Mapping function is described in the API docs here: https://doc.recognition.services.tiliter.com/#tag/Product-Mapping-and-Archetypes/operation/create_product_mapping

Here's how to map a product to an archetype using a Unix-like command-line interface:

curl -X POST "<https://api.tiliter.com/product_mappings"> -H "tiliter-api-key: YOUR_API_KEY" -d '{ "product_id": "apple123", "archetype_id": "43d1fe3d-0248-1182-851b-5e6a23f264f2" }'

Fields:

• product_id: The unique identifier for the product you created.
• archetype_id: The Tiliter Archetype ID.

Verifying Product Mappings

After mapping, it's a good practice to verify that the mappings are correct. You can list all product mappings with the following API call using a Unix-like command-line interface:

curl -X GET "<https://api.tiliter.com/product_mappings"> -H "tiliter-api-key: YOUR_API_KEY"

This will return a list of all product mappings, allowing you to verify that your products are correctly mapped to their corresponding Tiliter Archetypes.

Ongoing Mapping Management

New products are added to the product catalogue all the time. When each new product is added to the product catalogue, these products must be mapped to Tiliter Archetypes just like existing products were.

The process is exactly the same from a technical perspective. It is recommended to establish practices and processes that ensure that product mapping within the Tiliter Recognition API is part of the standard checklist of work required to introduce a new product into any store.

Conclusion

The Recognition API can only recognize products that are in the product catalogue, and mapped to a Tiliter Archetype (and in stock). Mapping products is required to use the Recognition API. Good management of product mapping will result in the best outcomes, performance, and accurate and useful usage and performance statistics. For more information, see Product Mapping and Archetypes.