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

200

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 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

200

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 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

200

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 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_tag`s 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

200

Content type

application/json

{"count": 0,
"questions": ["string"
],
"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

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

200

Content type

application/json

{"insights": [{"id": "3cd5aecd-edcc-4237-87d0-6595fc4e53c9",
"type": "label",
"barcode": 9782012805866
}
]
}

Get all insights for a specific product

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

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).

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 Annotation of the prediction: 1 to accept the prediction, 0 to refuse it, and -1 for skip
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

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

200

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

Import an new image in Robotoff

This endpoint is used by Product Opener to notify Robotoff that a new image has been uploaded in Open Food Facts database. The import operation is not performed directly by Robotoff API but added to a task queue that is consumed by Robotoff workers asynchronously.

Providing URLs of both the image and the OCR JSON (generated by Google Cloud Vision service) is required.

Request Body schema: application/x-www-form-urlencoded

barcode required	string Barcode of the product
image_url required	string <uri> URL of the image to be imported
ocr_url required	string <uri> URL of the OCR JSON file associated with the image
server_domain required	string (ServerDomainParameter) Enum: "api.openfoodfacts.org" "api.openbeautyfacts.org" "api.openproductfacts.org" "api.openpetfoodfacts.org" "api.pro.openfoodfacts.org" The server domain associated with the image/product. If the `server_domain` top level domain does not match the server configuration, an HTTP 400 error will be raised

Responses

Response samples

200
400

Content type

application/json

{"status": "scheduled"
}

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

200

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

200

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

200

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

200

Content type

application/json

{"results": [{"logo_id": 1,
"distance": 0.1
}
],
"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

200

Content type

application/json

{"results": [{"logo_id": 1,
"distance": 0.1
}
],
"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

Payload

Content type

application/json

{"product": {"product_name": "roasted chicken",
"ingredients_tags": ["en:chicken",
"en:salts"
],
"image_embeddings": [[0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0
]
],
"ocr": ["string"
],
"nutriments": {"fat_100g": 0,
"saturated-fat_100g": 0,
"carbohydrates_100g": 0,
"sugars_100g": 0,
"fiber_100g": 0,
"proteins_100g": 0,
"salt_100g": 0,
"energy-kcal_100g": 0,
"fruits-vegetables-nuts_100g": 0
}
},
"deepest_only": true,
"threshold": 0.5
}

Response samples

200

Content type

application/json

{"neural": [{"value_tag": "en:roast-chicken",
"confidence": 0.6
}
]
}

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

200

Content type

application/json

{"predictions": {"nutrients": { },
"predictor_version": "1",
"predictor": "regex",
"source_image": "string"
},
"image_ids": [0
],
"errors": [{"error": "string",
"error_description": "string"
}
]
}

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

200

Content type

application/json

{"predictions": [{"barcode": "5410041040807",
"type": "category",
"timestamp": "2023-05-13 02:10:09.107262",
"data": { },
"value_tag": "en:beverages",
"value": null,
"automatic_processing": false,
"source_image": "541/004/104/0807/3.jpg",
"id": 1522429,
"predictor_version": "keras-image-embeddings-3.0",
"predictor": "neural",
"server_type": "off",
"confidence": 0.95
}
]
}

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

200

Content type

application/json

{"predictions": [{"lang": "en",
"confidence": 0.9
}
]
}

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

200

Content type

application/json

{"counts": [{"lang": "en",
"count": 10
}
],
"percent": [{"lang": "en",
"percent": 80.5
}
],
"image_ids": [1
]
}