Difference between revisions of "Open Food Facts Search API Version 2"
(11 intermediate revisions by 2 users not shown) | |||
Line 2: | Line 2: | ||
== Introduction == | == Introduction == | ||
+ | |||
+ | '''NOTE''': '''We're now extracting search to [[Search-a-licious]], which has an OpenAPI documentation, an Elastic-Search backend and everything you'd expect from a modern search API.''' | ||
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). | 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). | ||
Line 26: | Line 28: | ||
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. | 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 | + | The new search API introduces 2 new endpoints that mimics 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 | * /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 | * /api/v2/search will return JSON results, with the exact same parameters as the /search endpoint | ||
+ | |||
+ | === Selection of the fields returned === | ||
+ | |||
+ | It is possible to specify which fields are returned for each result: | ||
+ | |||
+ | * [https://world.openfoodfacts.org/api/v2/search?categories_tags=en:meals&fields=code,product_name,brands,attribute_groups fields=code,product_name,brands,attribute_groups] | ||
=== Simplified parameters specification === | === Simplified parameters specification === | ||
Tags fields are now specified directly: | Tags fields are now specified directly: | ||
− | * labels_tags=en:organic | + | * [https://world.openfoodfacts.org/api/v2/search?labels_tags=en:organic&fields=code,product_name,labels_tags labels_tags=en:organic] |
− | * labels_tags_fr=bio -> bio is assumed to be in French and thus converted to en:organic | + | * [https://world.openfoodfacts.org/api/v2/search?labels_tags_fr=bio&fields=code,product_name,labels_tags_en labels_tags_fr=bio] -> bio is assumed to be in French and thus converted to en:organic |
For AND queries, use comma separated values: | For AND queries, use comma separated values: | ||
− | * labels_tags=en:organic,en:fair-trade | + | * [https://world.openfoodfacts.org/api/v2/search?labels_tags=en:organic,en:fair-trade&fields=code,product_name,labels_tags labels_tags=en:organic,en:fair-trade] |
For negative queries, prefix tag with - | For negative queries, prefix tag with - | ||
− | * labels_tags=-en:organic,-en:fair-trade | + | * [https://world.openfoodfacts.org/api/v2/search?labels_tags=en:organic,-en:fair-trade&fields=code,product_name,labels_tags labels_tags=-en:organic,-en:fair-trade] |
=== OR tags fields queries === | === OR tags fields queries === | ||
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 | + | * [https://world.openfoodfacts.org/api/v2/search?labels_tags=en:organic|en:fair-trade|en:some-other-label&fields=code,product_name,labels_tags labels_tags=en:organic|en:fair-trade|en:some-other-label] |
=== Conditions on nutrients === | === Conditions on nutrients === | ||
* Per 100g or per serving | * Per 100g or per serving | ||
− | ** energy-kj_100g < 200 | + | ** [https://world.openfoodfacts.org/api/v2/search?categories_tags=en:sodas&energy-kj_100g%3C200&fields=code,product_name,energy-kj_100g energy-kj_100g<200] |
− | ** sugars_serving > 10 | + | ** [https://world.openfoodfacts.org/api/v2/search?categories_tags=en:sodas&sugars_serving%3E10g&fields=code,product_name,sugars_serving sugars_serving>10] |
* Per the product as sold, or prepared | * Per the product as sold, or prepared | ||
− | ** saturated-fat_100g (as sold) | + | ** [https://world.openfoodfacts.org/api/v2/search?categories_tags=en:sodas&saturated-fat_100g=1&fields=code,product_name,saturated-fat_100g saturated-fat_100g=1] (as sold) |
− | ** salt_prepared_serving (prepared, per serving) | + | ** [https://world.openfoodfacts.org/api/v2/search?categories_tags=en:meals&salt_prepared_serving=1&fields=code,product_name,salt_prepared_serving salt_prepared_serving] (prepared, per serving) |
== Development and deployment == | == Development and deployment == | ||
Line 76: | Line 84: | ||
* [https://github.com/openfoodfacts/openfoodfacts-server/pull/4133 New Search API features + New Product Attributes] | * [https://github.com/openfoodfacts/openfoodfacts-server/pull/4133 New Search API features + New Product Attributes] | ||
* [https://github.com/openfoodfacts/openfoodfacts-server/pull/4240 New /search endpoint] | * [https://github.com/openfoodfacts/openfoodfacts-server/pull/4240 New /search endpoint] | ||
+ | |||
+ | == See also == | ||
+ | |||
+ | [[Open Food Facts API Version 2]] | ||
[[Category:Project:Personalized_Search]] | [[Category:Project:Personalized_Search]] | ||
[[Category:ProductOpener]] | [[Category:ProductOpener]] | ||
+ | [[Category:API]] | ||
+ | [[Category:Search]] |
Latest revision as of 09:13, 15 August 2024
Open Food Facts Search API Version 2
Introduction
NOTE: We're now extracting search to Search-a-licious, which has an OpenAPI documentation, an Elastic-Search backend and everything you'd expect from a modern search API.
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:
- 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)
- https://world.openfoodfacts.org/search?categories_tags_en=chocolates&labels_tags_en=organic,fair%20trade (corresponding Web site endpoint)
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 mimics 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
Selection of the fields returned
It is possible to specify which fields are returned for each result:
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:
For negative queries, prefix tag with -
OR tags fields queries
For OR queries, use | to separate values
Conditions on nutrients
- Per 100g or per serving
- Per the product as sold, or prepared
- saturated-fat_100g=1 (as sold)
- salt_prepared_serving (prepared, per serving)
Development and deployment
The new Search API V2 has been developed and deployed incrementally in August and September 2020. The new V2 API 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.
Related issues
Related PRs
- New search API + simplified parameter handling
- Support conditions on nutrients for new search API
- Return only specific nutrients through the API
- New Search API features + New Product Attributes
- New /search endpoint