Open Food Facts Search API Version 2: Difference between revisions
(Adding examples of V2 of the API, clarification of the ongoing support for V1) |
(→Examples: V1 and V2 of the API) |
||
| Line 14: | Line 14: | ||
Products from the chocolate category, with both the organic label and the fair trade label: | Products from the chocolate category, with both the organic label and the fair trade label: | ||
* V1: | * V1: https://world.openfoodfacts.org/cgi/search.pl?action=process&tagtype_0=categories&tag_contains_0=contains&tag_0=chocolates&tagtype_1=labels&tag_contains_1=contains&tag_1=organic&tagtype_2=labels&tag_contains_2=contains&tag_2=fair-trade&json=1 (cannot select the fields returned) | ||
* V2: https://world.openfoodfacts.org/api/v2/search?categories_tags_en=chocolates&labels_tags_en=organic,fair%20trade&fields=code,product_name | * V2: https://world.openfoodfacts.org/api/v2/search?categories_tags_en=chocolates&labels_tags_en=organic,fair%20trade&fields=code,product_name (returns only selected fields) | ||
== Features == | == Features == | ||
Revision as of 09:41, 13 October 2020
Open Food Facts Search API Version 2
Introduction
Version 1 of the 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 have thus created a new Open Food Facts Search API Version 2 that is simpler but also more powerful.
- Version 1 of the API will continue to be supported for the years to come, as there are many apps that are using it.
- Version 2 of the API was launched in production in September 2020. It has not been widely publicized yet as we may change it based on the feedback of the first users.
Examples
Products from the chocolate category, with both the organic label and the fair trade label:
- V1: https://world.openfoodfacts.org/cgi/search.pl?action=process&tagtype_0=categories&tag_contains_0=contains&tag_0=chocolates&tagtype_1=labels&tag_contains_1=contains&tag_1=organic&tagtype_2=labels&tag_contains_2=contains&tag_2=fair-trade&json=1 (cannot select the fields returned)
- V2: https://world.openfoodfacts.org/api/v2/search?categories_tags_en=chocolates&labels_tags_en=organic,fair%20trade&fields=code,product_name (returns only selected fields)
Features
New /api/v2/search (JSON) and /search (OFF web site) endpoints
V1 of the 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 has been be developed and deployed incrementally, and it co-exists with the existing Search API V1.
V1 of the API will be supported for the years to come as many apps are using it.