Open Food Facts Search API Version 2

From Open Food Facts wiki
Revision as of 09:13, 15 August 2024 by Teolemon (talk | contribs) (→‎Open Food Facts Search API Version 2)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)

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:

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:

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

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

See also

Open Food Facts API Version 2