API usage for getting similar products with scoring

on


Note: the Prosim Engine delivers matching products with similarity and score details. Check its stats records here.

Daily statistics on   S C O R E    databases are available here.

Let P be the product reference (barcode) for which you want to get similar products, C the country and S the store for restricting results, here are the Rest API endpoints delivered by the tuttifrutti.alwaysdata.net website to retrieve this information:



Endpoint Parameters Results
fetchScoreDbs n/a try it!

JSON returned: timestamp of last updates + characteristics of the graphs related to the nutritional Mongo-Databases available on the server (min. and max values for scores, labels for graph, etc.) + statistics on stored data.

Typically, it is used by the Statistics link provided at the top of this article.
fetchP barcode=P
score=R 		Nutriscore: try it!
Novascore: try it!
R = nutriscore | novascore | ...
JSON returned: product reference [P]
Fetches record details for P: most common data from officiel OFF-database along with similarity details (no restrictions apply, except for the minimum similarity percentage; check it in tuning & configuration).
fetchPMatch barcode=P
score=R
[country=C]
[store=S] 		Nutriscore: try it!
Novascore: try it!
R = nutriscore | novascore | ...
JSON returned: product reference [P] + matching products
Fetches record details for P in R database, and retrieves details for each product referenced in similarity tag for those belonging to C and S if stated (no restrictions apply, except for the minimum similarity percentage; check it in tuning & configuration).
fetchPGraph barcode=P
score=R
[country=C]
[store=S]		 Nutriscore: try it!
Novascore: try it!
R = nutriscore | novascore | ...
useful only for the tuttifruti website-graph (restrictions on the set of returned products do apply! Check below).
It performs the following tasks:
  • same as fetchPMatch
  • computes (x, y) coordinates in the graph for showing a product based on its similarity percentage with P and its scoring (nutrition-score, nova-score, etc.)
  • furthermore, it restricts the set of similar products in accordance to the similarity percentage and scoring of P. E.g.: if P has a score of 3 (yellow=average), it is very not useful nor desired to show too many other products more or less similar which offer a worse scoring quality
Note: for historical reasons, the (x, y) coordinates are computed server-side. But in the future for performance reasons, the server could be leveraged by letting the browser compute these coordinates instead. 		/

fetchP

fetchP retrieves record data of product P which are made of the following:
  • standard OFF data tags such as brands_tags, categories_tags, product_name, nutriments, ...
  • an extra tag which is called similarity. The similarity tag is dedicated for listing products which are similar to P with a certain percentage and then categorized by their score (nutrition-score, nova-score, your own score eventually, depending on the value you provide for R). This computation is performed by the PROSIM project
    • which you are free to adapt based on your own needs

fetchPMatch

This method returns a set made of 2 properties:
  • product_reference: standard details from the OFF database along with the property similarity delivered by the PROSIM engine
  • matching_products: array of details for all matching products (all stated in the similarity tag of product_reference). A filter may apply if C and S have been specified in the called URL

Default database is nutriscore but you may choose another score-database by setting R accordingly.

JSON sample with country "France" and Store "Auchan":
https://tuttifrutti.alwaysdata.net/fetchPMatch/?barcode=3596710024087&country=en%3Afrance&store=auchan
As you may notice in the enclosed screenshot below, the similarity tag provides all similar products, BUT a filtering on country and store has been applied to show only relevant matching products! The one highlighted has a similarity with product reference of 80% and a nutrition score of 4.

fetchPGraph

This API method is dedicated to the tuttifrutti website for generating the graph. All computations are server-based which is actually a bad practise. For this reason, users are invited to use the previous methods intead.
However, here is a short description of the result returned by this call:


This object is made of the following items:
  • the graph main object:
  • [yellow].. containing a first item which details the product reference for which you have entered the barcode in the url:
    • it holds the (x_val_real,y_val_real) coordinates used for positioning the product in the graph shown using an ellipse:
    • x_val_rel = 1 always it is always drawn on the right-most part of the graph (X-axis stands for the similarity with product refrence, which is obviously 100% similar to itself!)
    • y_val_real = nutrition_score always so that the product is shown in the right colour banner standing for its nutrition grade
  • [pink & green].. containing an array of similar products:
    • [pink] one product similar to the product reference with a score of 60% in similarity (more details...) and a nutrition score of 2. Similarity is used for computing the x coordinate in the graph whereas the nutrition score is used for the y coordinate (see below).
    • [green] a second product similar to the product reference

Further reading:

Comments

Post a Comment