Product Mapping
This page introduces the concept of Tiliter Archetypes, and describes the processing of mapping products to them.
Introduction
![](https://files.readme.io/d8ecfd3-Screenshot_2024-03-08_at_9.53.02_am.png)
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.
![](https://files.readme.io/bac445e-Screenshot_2023-11-13_at_6.18.39_pm.png)
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:
Retailer Product ID | Product name used in store |
---|---|
834437 | Large Banana |
930655 | Loose Limes |
567001 | Portobello mushrooms |
129554 | Red Bell Pepper |
290123 | Opal Apple |
645433 | Yello Apple |
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
Retailer Product ID | Product name used in store | Tiliter Archetype ID | Tiliter Archetype Name |
---|---|---|---|
834437 | Large Banana | ||
930655 | Loose Limes | ||
567001 | Portobello mushrooms | ||
129554 | Red Bell Pepper | ||
290123 | Opal Apple | ||
645433 | Yello Apple |
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:
Retailer product ID | Retailer product name | Tiliter Archetype ID | Tiliter Archetype Name |
---|---|---|---|
834437 | Large Banana | 11059-c97a-b1 | Banana Cavendish |
930655 | Loose Limes | 83a15-00bm-4a | Lime |
567001 | Portobello mushrooms | 78gfd-453j-bf | Mushroom Portobello |
129554 | Red Bell Pepper | ||
290123 | Opal Apple | ||
645433 | Yello Apple |
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:
Names used in Tiliter Archetype | Alternative Names |
---|---|
Eggplant | Aubergine |
Zucchini | Courgette |
Capsicum | Bell Pepper |
Silverbeet | Swiss Chard |
Swede | Rutabaga |
Rockmelon | Cantaloupe |
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:
Retailer product ID | Retailer product name | Tiliter Archetype ID | Tiliter Archetype Name |
---|---|---|---|
834437 | Large Banana | 11059-c97a-b1 | Banana Cavendish |
930655 | Loose Limes | 83a15-00bm-4a | Lime |
567001 | Portobello mushrooms | 78gfd-453j-bf | Mushroom Portobello |
923sd-f4r4-5d | Red Bell Pepper | 923sd-f4r4-5d | Capsicum Red |
290123 | Opal Apple | ||
645433 | Yello Apple |
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:
Retailer Product ID | Retailer Product Name | Tiliter Archetype ID | Tiliter Archetype Name |
---|---|---|---|
834437 | Large Banana | 11059-c97a-b1 | Banana Cavendish |
930655 | Loose Limes | 83a15-00bm-4a | Lime |
567001 | Portobello mushrooms | 78gfd-453j-bf | Mushroom Portobello |
129554 | Red Bell Pepper | 923sd-f4r4-5d | Capsicum Red |
290123 | Opal Apple | 147dy-74d6-67 | Apple Yellow |
645433 | Yello Apple | 147dy-74d6-67 | Apple Yellow |
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
Retailer Product ID | Retailer Product Name | Tiliter Archetype ID | Tiliter Archetype Name |
---|---|---|---|
834437 | Large Banana | 11059-c97a-b1 | Banana Cavendish |
930655 | Loose Limes | 83a15-00bm-4a | Lime |
567001 | Portobello mushrooms | 78gfd-453j-bf | Mushroom Portobello |
567001 | Portobello mushrooms | 54g9d-64gg-a9 | Mushroom Brown Bag |
129554 | Red Bell Pepper | 923sd-f4r4-5d | Capsicum Red |
290123 | Opal Apple | 147dy-74d6-67 | Apple Yellow |
645433 | Yello Apple | 147dy-74d6-67 | Apple Yellow |
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.
Updated 6 months ago
Read the next section, Product Stock Management