Difference between revisions of "Open Food Facts Search API Version 2"

From Open Food Facts wiki
Jump to navigation Jump to search
Line 35: Line 35:
 
For OR queries, use | to separate values
 
For OR queries, use | to separate values
 
* labels_tags=en:organic|en:fair-trade|en:some-other-label
 
* labels_tags=en:organic|en:fair-trade|en:some-other-label
 +
 +
=== Conditions on nutrients ===
 +
 +
* Per 100g or per serving
 +
** energy-kj_100g < 200
 +
** sugars_serving > 10
 +
* Per the product as sold, or prepared
 +
** saturated-fat_100g (as sold)
 +
** salt_prepared_serving (prepared, per serving)
  
 
== Development and deployment ==
 
== Development and deployment ==
Line 45: Line 54:
  
 
=== Nutrients ===
 
=== Nutrients ===
 +
 +
* [https://github.com/openfoodfacts/openfoodfacts-server/issues/4075 New search API - conditions on nutrients #4075]
  
 
=== Other fields ===
 
=== Other fields ===

Revision as of 17:53, 26 August 2020

Open Food Facts Search API Version 2

Introduction

The existing Open Food Facts search API is outdated and hacky (it was built on top of the OFF web site search form and is unnecessarily convoluted) and does not support some of the requirements for the Project:Personalized_Search (in particular being able to retrieve a given set of products using their barcodes).

We are thus creating a new Open Food Facts Search API Version 2 that will be simpler but also more powerful.

Features

New /api/v2/search (JSON) and /search (OFF web site) endpoints

The current search API is a hack on the web site search form and is accessed by adding &json=1 to the /cgi/search.pl web form.

The new search API introduces 2 new endpoints that mimick the product page endpoints (/product/[barcode] for the Web, and /api/v0/product/[barcode] for the API with JSON results):

  • /search will replace /cgi/search.pl as the url of search results
  • /api/v2/search will return JSON results, with the exact same parameters as the /search endpoint

Simplified parameters specification

Tags fields are now specified directly:

  • labels_tags=en:organic
  • labels_tags_fr=bio -> bio is assumed to be in French and thus converted to en:organic

For AND queries, use comma separated values:

  • labels_tags=en:organic,en:fair-trade

For negative queries, prefix tag with -

  • labels_tags=-en:organic,-en:fair-trade

OR tags fields queries

For OR queries, use | to separate values

  • labels_tags=en:organic|en:fair-trade|en:some-other-label

Conditions on nutrients

  • Per 100g or per serving
    • energy-kj_100g < 200
    • sugars_serving > 10
  • Per the product as sold, or prepared
    • saturated-fat_100g (as sold)
    • salt_prepared_serving (prepared, per serving)

Development and deployment

The new Search API V2 will be developed and deployed incrementally, and it will co-exist with the existing Search API V1. V1 of the API will not be deprecated until V2 covers an extensive all needed search features.

Tags fields

Nutrients

Other fields

e.g. product name