API Reference (1.0)

Download OpenAPI specification:Download

Robotoff provides a simple API allowing consumers to fetch predictions and annotate them.

All endpoints must be prefixed with /api/v1. The full URL is https://robotoff.openfoodfacts.org/api/v1/{endpoint}.

Questions

Get questions for a given product

Questions are sorted by priority: we want questions with highest impact to be displayed first. The order is the following:

  • category
  • label
  • brand
  • remaining types
path Parameters
barcode
required
integer
Example: 5410041040807

The barcode of the product

query Parameters
count
integer >= 1
Default: 1

The number of questions to return

server_type
string
Default: "off"
Enum: "off" "obf" "opff" "opf" "off_pro"

The server type (=project) to use, such as 'off' (Open Food Facts), 'obf' (Open Beauty Facts),...

lang
string
Default: "en"

The language of the question/value

insight_types
string
Example: insight_types=brand,label

Comma-separated list, filter by insight types

Responses

Response samples

Content type
application/json
{
  • "status": "no_questions",
  • "questions": [
    ]
}

Fetch questions

query Parameters
lang
string
Default: "en"

The language of the question/value

count
integer >= 1
Default: 25

The number of items to return

server_type
string
Default: "off"
Enum: "off" "obf" "opff" "opf" "off_pro"

The server type (=project) to use, such as 'off' (Open Food Facts), 'obf' (Open Beauty Facts),...

insight_types
string
Example: insight_types=brand,label

Comma-separated list, filter by insight types

countries
string
Example: countries=uk

Comma separated list, filter by country value (2-letter code)

brands
string
Example: brands=carrefour,ferrero

Comma-separated list, filter by brands

value_tag
string
Example: value_tag=en:organic

Filter by value tag, i.e the value that is going to be sent to Product Opener

page
integer >= 1
Default: 1

Page index to return (starting at 1)

reserved_barcode
boolean
Default: false

If true, also return questions about products with reserved barcodes

campaigns
string
Example: campaigns=agribalyse-category

Filter by annotation campaigns (the insight must have all the campaigns) An annotation campaigns allows to only retrieve questions about selected products, based on arbitrary criteria

predictor
string
Example: predictor=universal-logo-detector

Filter by predictor value A predictor refers to the model/method that was used to generate the prediction.

order_by
string
Default: "popularity"
Enum: "confidence" "random" "popularity"

The field to use for ordering results:

  • confidence: order by (descending) model confidence, null confidence insights come last
  • popularity: order by (descending) popularity (=scan count)
  • random: use a random order

Responses

Response samples

Content type
application/json
{
  • "status": "no_questions",
  • "questions": [
    ],
  • "count": 0
}

Get random questions Deprecated

query Parameters
lang
string
Default: "en"

The language of the question/value

count
integer >= 1
Default: 25

The number of items to return

server_type
string
Default: "off"
Enum: "off" "obf" "opff" "opf" "off_pro"

The server type (=project) to use, such as 'off' (Open Food Facts), 'obf' (Open Beauty Facts),...

insight_types
string
Example: insight_types=brand,label

Comma-separated list, filter by insight types

countries
string
Example: countries=uk

Comma separated list, filter by country value (2-letter code)

brands
string
Example: brands=carrefour,ferrero

Comma-separated list, filter by brands

value_tag
string
Example: value_tag=en:organic

Filter by value tag, i.e the value that is going to be sent to Product Opener

page
integer >= 1
Default: 1

Page index to return (starting at 1)

reserved_barcode
boolean
Default: false

If true, also return questions about products with reserved barcodes

campaigns
string
Example: campaigns=agribalyse-category

Filter by annotation campaigns (the insight must have all the campaigns) An annotation campaigns allows to only retrieve questions about selected products, based on arbitrary criteria

predictor
string
Example: predictor=universal-logo-detector

Filter by predictor value A predictor refers to the model/method that was used to generate the prediction.

Responses

Response samples

Content type
application/json
{
  • "status": "no_questions",
  • "questions": [
    ],
  • "count": 0
}

Get questions about popular products Deprecated

Questions are ranked by the product popularity (based on scan count).

query Parameters
lang
string
Default: "en"

The language of the question/value

count
integer >= 1
Default: 25

The number of items to return

server_type
string
Default: "off"
Enum: "off" "obf" "opff" "opf" "off_pro"

The server type (=project) to use, such as 'off' (Open Food Facts), 'obf' (Open Beauty Facts),...

insight_types
string
Example: insight_types=brand,label

Comma-separated list, filter by insight types

countries
string
Example: countries=uk

Comma separated list, filter by country value (2-letter code)

brands
string
Example: brands=carrefour,ferrero

Comma-separated list, filter by brands

value_tag
string
Example: value_tag=en:organic

Filter by value tag, i.e the value that is going to be sent to Product Opener

page
integer >= 1
Default: 1

Page index to return (starting at 1)

reserved_barcode
boolean
Default: false

If true, also return questions about products with reserved barcodes

campaigns
string
Example: campaigns=agribalyse-category

Filter by annotation campaigns (the insight must have all the campaigns) An annotation campaigns allows to only retrieve questions about selected products, based on arbitrary criteria

predictor
string
Example: predictor=universal-logo-detector

Filter by predictor value A predictor refers to the model/method that was used to generate the prediction.

Responses

Get unanswered question counts

Get number of unanswered questions grouped by value_tag. The list is ordered from highest count to lowest.

query Parameters
count
number >= 1
Default: 25

The number of distinct value_tags to return

server_type
string
Default: "off"
Enum: "off" "obf" "opff" "opf" "off_pro"

The server type (=project) to use, such as 'off' (Open Food Facts), 'obf' (Open Beauty Facts),...

type
string

Filter by insight type

countries
string
Example: countries=uk

Comma separated list, filter by country value (2-letter code)

page
integer >= 1
Default: 1

Page index to return (starting at 1)

reserved_barcode
boolean
Default: false

If true, also return questions about products with reserved barcodes

campaigns
string
Example: campaigns=agribalyse-category

Filter by annotation campaigns (the insight must have all the campaigns) An annotation campaigns allows to only retrieve questions about selected products, based on arbitrary criteria

predictor
string
Example: predictor=universal-logo-detector

Filter by predictor value A predictor refers to the model/method that was used to generate the prediction.

Responses

Response samples

Content type
application/json
{
  • "count": 0,
  • "questions": [
    ],
  • "status": "found"
}

Insights

An insight is a fact about a product that has been either extracted or inferred from the product pictures, characteristics,... If the insight is correct, the Openfoodfacts DB can be updated accordingly.

Current insight types and their description can be found in robotoff/insights/dataclass.py.

Get a random insight, use GET /insights?order_by=random instead Deprecated

query Parameters
type
string

Filter by insight type

countries
string
Example: countries=uk

Comma separated list, filter by country value (2-letter code)

value_tag
string
Example: value_tag=en:organic

Filter by value tag, i.e the value that is going to be sent to Product Opener

server_type
string
Default: "off"
Enum: "off" "obf" "opff" "opf" "off_pro"

The server type (=project) to use, such as 'off' (Open Food Facts), 'obf' (Open Beauty Facts),...

count
integer >= 1
Default: 25

The number of items to return

predictor
string
Example: predictor=universal-logo-detector

Filter by predictor value A predictor refers to the model/method that was used to generate the prediction.

Responses

Response samples

Content type
application/json
{
  • "insights": [
    ]
}

Get all insights for a specific product, use GET /insights?barcode={barcode} instead Deprecated

path Parameters
barcode
required
integer
Example: 5410041040807

The barcode of the product

query Parameters
server_type
string
Default: "off"
Enum: "off" "obf" "opff" "opf" "off_pro"

The server type (=project) to use, such as 'off' (Open Food Facts), 'obf' (Open Beauty Facts),...

Responses

List insights

query Parameters
insight_types
string
Example: insight_types=brand,label

Comma-separated list, filter by insight types

barcode
integer
Example: barcode=5410041040807

Filter by barcode value

annotated
boolean
Example: annotated=true

Filter by annotation status of the insight. A true value (1, true) means we only return annotated insights, a false value (0, false) only non-annotated insights. If the parameter is not provided, both annotated and non-annotated insights are returned.

annotation
integer
Example: annotation=1

Filter by annotation value of the insight. If not provided, all insights are returned. This works in conjunction with the annotated parameter.

value_tag
string
Example: value_tag=en:organic

Filter by value tag, i.e the value that is going to be sent to Product Opener

brands
string
Example: brands=carrefour,ferrero

Comma-separated list, filter by brands

countries
string
Example: countries=uk

Comma separated list, filter by country value (2-letter code)

server_type
string
Default: "off"
Enum: "off" "obf" "opff" "opf" "off_pro"

The server type (=project) to use, such as 'off' (Open Food Facts), 'obf' (Open Beauty Facts),...

predictor
string
Example: predictor=universal-logo-detector

Filter by predictor value A predictor refers to the model/method that was used to generate the prediction.

order_by
string
Enum: "random" "popularity"
Example: order_by=popularity

How to order by insight results. By default, results are not ordered. Possible values are:

  • random: insights are ordered randomly
  • popularity: insights are returned by decreasing popularity, using the number of scans as proxy
count
integer >= 1
Default: 25

The number of items to return

page
integer >= 1
Default: 1

Page index to return (starting at 1)

Responses

Response samples

Content type
application/json
{
  • "insights": [
    ],
  • "status": "found",
  • "count": 10
}

Get a specific insight

path Parameters
id
required
string

ID of the insight

Responses

Submit an annotation

The annotation can be submitted as an anonymous user or as a registered user. If the user is anonymous, the annotation will be accounted as a vote, and several identical anonymous votes are required to apply the insight. If the vote is sent from a registered user, it is applied directly.

To send the annotation as a registered user, send Open Food Facts credentials to the API using Basic Authentication: add a Authorization: basic {ENCODED_BASE64} header where {ENCODED_BASE64} is an base64-encoded string of user:password. Don't provide an authentication header for anonymous users.

The annotation is an integer that can take 4 values: 0, 1, 2, -1. 0 means the insight is incorrect (so it won't be applied), 1 means it is correct (so it will be applied) and -1 means the insight won't be returned to the user (skip). 2 is used when user submit some data to the annotate endpoint (for example in some cases of category annotation or ingredients spellcheck).

We use the voting mecanism system to remember which insight to skip for a user (authenticated or not).

Request Body schema: application/x-www-form-urlencoded
insight_id
required
string

ID of the insight

annotation
required
integer
Enum: 0 1 -1 2

Annotation of the prediction: 1 to accept the prediction, 0 to refuse it, and -1 for skip, 2 to accept and add data

update
integer
Default: 1
Enum: 0 1

Send the update to Openfoodfacts if update=1, don't send the update otherwise. This parameter is useful if the update is performed client-side

data
object

Additional data provided by the user as key-value pairs

Responses

Generate a CSV dump

Generate a CSV dump of insights with specific criteria. If more than 10,000 insights match provided criteria and count is not provided, a HTTP 400 is returned

query Parameters
server_type
string
Default: "off"
Enum: "off" "obf" "opff" "opf" "off_pro"

The server type (=project) to use, such as 'off' (Open Food Facts), 'obf' (Open Beauty Facts),...

value_tag
string
Example: value_tag=en:organic

Filter by value tag, i.e the value that is going to be sent to Product Opener

insight_types
string
Example: insight_types=brand,label

Comma-separated list, filter by insight types

barcode
string
Example: barcode=5410041040807

Filter by barcode value

annotated
boolean
Default: null

The annotation status of the insight. If not provided, both annotated and non-annotated insights are returned

count
integer [ 0 .. 10000 ]
Default: null

Maximum number of insights to return. If not provided, an HTTP 400 response may be returned if more than 10,000 insights match the criteria

Responses

Predictions

Get predictions

query Parameters
count
integer >= 1
Default: 25

The number of items to return

page
integer >= 1
Default: 1

Page index to return (starting at 1)

server_type
string
Default: "off"
Enum: "off" "obf" "opff" "opf" "off_pro"

The server type (=project) to use, such as 'off' (Open Food Facts), 'obf' (Open Beauty Facts),...

barcode
string
Example: barcode=5410041040807

Filter by barcode value

types
string
Example: types=brand,label

Comma-separated list, filter by prediction types

Responses

Response samples

Content type
application/json
{
  • "status": "no_predictions",
  • "predictions": [
    ],
  • "count": 0
}

Images

Crop an image

This endpoint is currently only used to generate cropped logos on Hunger Games from a base image and cropping coordinates. Cropping coordinates are relative (between 0. and 1. inclusive), with (0, 0) being the upper left corner.

query Parameters
image_url
string <uri>
Example: image_url=https://static.openfoodfacts.org/images/products/211/123/200/5508/3.jpg
y_min
number [ 0 .. 1 ]
Example: y_min=0.47795143723487854
x_min
number [ 0 .. 1 ]
Example: x_min=0.5583494305610657
y_max
number [ 0 .. 1 ]
Example: y_max=0.5653171539306641
x_max
number [ 0 .. 1 ]
Example: x_max=0.6795185804367065

Responses

Image Predictions

Get image predictions

query Parameters
count
integer >= 1
Default: 25

The number of items to return

page
integer >= 1
Default: 1

Page index to return (starting at 1)

server_type
string
Default: "off"
Enum: "off" "obf" "opff" "opf" "off_pro"

The server type (=project) to use, such as 'off' (Open Food Facts), 'obf' (Open Beauty Facts),...

barcode
string
Example: barcode=5410041040807

Filter by barcode value

with_logo
boolean
Default: false

if True, only return image predictions that have associated logos (only valid for universal-logo-detector image predictions)

model_name
string
Enum: "universal-logo-detector" "nutrition-table" "nutriscore"

filter by name of the image predictor model

type
string
Value: "object_detection"

filter by type of the image predictor model, currently only 'object_detection'

model_version
string

filter by model version value

min_confidence
number [ 0 .. 1 ]

filter by minimum confidence score value

Responses

Response samples

Content type
application/json
{
  • "status": "no_image_predictions",
  • "image_predictions": [
    ],
  • "count": 0
}

Logos

Fetch logos

Return details about requested logos (maximum 500 logos can be fetched per request).

query Parameters
logo_ids
string

Comma-separated string of logo IDs

Responses

Response samples

Content type
application/json
{
  • "logos": [ ],
  • "count": 0
}

Search for logos

Search for logos detected using the universal-logo-detector model that meet some criteria (annotation status, annotated, type,...)

query Parameters
server_type
string
Default: "off"
Enum: "off" "obf" "opff" "opf" "off_pro"

The server type (=project) to use, such as 'off' (Open Food Facts), 'obf' (Open Beauty Facts),...

barcode
string
Example: barcode=5410041040807

Filter by barcode value

count
number [ 1 .. 2000 ]
Default: 25

Number of results to return

type
string
Example: type=packager_code

Filter by logo type

value
string
Example: value=lidl

Filter by annotated value

taxonomy_value
string
Example: taxonomy_value=en:organic

Filter by taxonomy value, i.e. the canonical value present is the associated taxonomy. This parameter is mutually exclusive with value, and should be used for label type.

min_confidence
number

Filter logos that have a confidence score above a threshold

random
boolean
Default: false

If true, randomized result order

annotated
boolean
Default: null

The annotation status of the logo. If not provided, both annotated and non-annotated logos are returned

Responses

Response samples

Content type
application/json
{
  • "logos": [ ],
  • "count": 0
}

Reset logo annotation

Reset logo annotations, and delete all annotation-associated predictions and insights

path Parameters
logo_id
required
integer
Example: 1

The ID of the logo whose annotation to reset

Responses

ANN

Approximate search for nearest neighbors of a random query logo

Return ID and distance of each logo found, the number of neighbors returned and the ID of the query logo.

query Parameters
count
integer [ 1 .. 2000 ]
Default: 25

Number of neighbors to return

server_type
string
Default: "off"
Enum: "off" "obf" "opff" "opf" "off_pro"

The server type (=project) to use, such as 'off' (Open Food Facts), 'obf' (Open Beauty Facts),...

Responses

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "count": 0,
  • "query_logo_id": 0
}

Approximate search for nearest neighbors of a specified query logo

Return ID and distance of each logo found, the number of neighbors returned and the ID of the query logo.

query Parameters
count
integer [ 1 .. 2000 ]
Default: 25

Number of neighbors to return

server_type
string
Default: "off"
Enum: "off" "obf" "opff" "opf" "off_pro"

The server type (=project) to use, such as 'off' (Open Food Facts), 'obf' (Open Beauty Facts),...

Responses

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "count": 0,
  • "query_logo_id": 0
}

Predict

Predict categories for a product

Predictions are performed using a neural model. As input, you can either provide:

  • the barcode of a product: Robotoff will fetch the product from Product Opener and will use this data as inputs to predict categories.
  • expected inputs under a product key. The neural category model accepts the following fields as input: product_name, ingredients_tags, ocr, nutriments, image_embeddings. All fields are optional (but you should at least provide one).
Request Body schema: application/json
Any of
barcode
required
string non-empty

The barcode of the product to categorize

server_type
string
Default: "off"
Enum: "off" "obf" "opff" "opf"

The server type (=project) to use, such as 'off' (Open Food Facts), 'obf' (Open Beauty Facts),... Only 'off' is currently supported for category prediction

deepest_only
boolean

If true, only return the deepest elements in the category taxonomy (don't return categories that are parents of other predicted categories)

threshold
number
Default: 0.5

The score above which we consider the category to be detected

Responses

Request samples

Content type
application/json
{
  • "product": {
    },
  • "deepest_only": true,
  • "threshold": 0.5
}

Response samples

Content type
application/json
{
  • "neural": [
    ]
}

Extract nutritional information from an image

We currently only use the OCR text as input, and detect nutrient-value pairs if they are consecutive to each other in the OCR text (ex: "protein: 10.5g, fat: 2.1g").

query Parameters
barcode
required
integer
Example: barcode=5410041040807

The barcode of the product

server_type
string
Default: "off"
Enum: "off" "obf" "opff" "opf" "off_pro"

The server type (=project) to use, such as 'off' (Open Food Facts), 'obf' (Open Beauty Facts),...

image_ids
string
Example: image_ids=1,2,5

a comma-separated list of IDs of images to extract nutritional information from. If not provided, the 10 most recent images will be used.

Responses

Response samples

Content type
application/json
{
  • "predictions": {
    },
  • "image_ids": [
    ],
  • "errors": [
    ]
}

Generate OCR predictions an OCR JSON

query Parameters
ocr_url
required
string <uri>
Example: ocr_url=https://static.openfoodfacts.org/images/products/216/124/000/3089/1.json

The URL of the OCR JSON to use for extraction

server_type
string
Default: "off"
Enum: "off" "obf" "opff" "opf" "off_pro"

The server type (=project) to use, such as 'off' (Open Food Facts), 'obf' (Open Beauty Facts),...

prediction_types
string
Example: prediction_types=category,label

a comma-separated list of prediction types to use for extraction. If not provided, we use the default: set of OCR prediction types (see DEFAULT_OCR_PREDICTION_TYPES variable in Robotoff codebase)

Responses

Response samples

Content type
application/json
{
  • "predictions": [
    ]
}

Predict the language of a text

Predict the language of a text using a neural model. A POST version of this endpoint is also available, it accepts a JSON body with exactly the same parameters.

Use the POST version if you want to predict the language of a long text, as the GET version has a limit on the length of the text that can be provided.

query Parameters
text
required
string
Example: text=hello world

The text to predict language of

k
integer >= 1
Default: 10

the number of predictions to return

threshold
number [ 0 .. 1 ]
Default: 0.01

the minimum probability for a language to be returned

Responses

Response samples

Content type
application/json
{
  • "predictions": [
    ]
}

Predict the languages of the product

Return the most common languages present on the product images, based on word-level language detection from product images.

Language detection is not performed on the fly, but is based on predictions of type image_lang stored in the prediction table.

query Parameters
barcode
required
integer
Example: barcode=5410041040807

The barcode of the product

server_type
string
Default: "off"
Enum: "off" "obf" "opff" "opf" "off_pro"

The server type (=project) to use, such as 'off' (Open Food Facts), 'obf' (Open Beauty Facts),...

Responses

Response samples

Content type
application/json
{
  • "counts": [
    ],
  • "percent": [
    ],
  • "image_ids": [
    ]
}

Batch Job

Import batch processed data to the Robotoff database.

Trigger import of the batch processed data to the Robotoff database. A BATCH_JOB_KEY is expected in the authorization header. This endpoint is mainly used by the batch job once the job is finished.

Authorizations:
batch_job_key
query Parameters
job_type
required
string
Value: "ingredients_spellcheck"

The type of batch job launched.

Responses