API docs by Redocly

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

Question Management

Endpoints for managing and retrieving questions about products that need human validation.

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 campaign allows to only retrieve questions or insights based on arbitrary criteria defined during insight import.

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 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 campaign allows to only retrieve questions or insights based on arbitrary criteria defined during insight import.

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

Insight Management

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.

List insights

Return insights based on various filters. The results can be filtered by insight type, barcode, annotation status, and more. The insight_types parameter is a comma-separated list of insight types to filter by. If no insight_types are provided, insights of all types are returned.

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)

campaigns
string
Example: campaigns=agribalyse-category

Filter by annotation campaigns (the insight must have all the campaigns) An annotation campaign allows to only retrieve questions or insights based on arbitrary criteria defined during insight import.

lc
string
Example: lc=en,fr,de

Comma-separated list of language codes to filter insights by language

Responses

Response samples

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

Get a specific insight

path Parameters
insight_id
required
string

ID of the insight

Responses

Response samples

Content type
application/json
{
  • "id": "3cd5aecd-edcc-4237-87d0-6595fc4e53c9",
  • "type": "label",
  • "barcode": 9782012805866,
  • "countries": [
    ]
}

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

Authorizations:
basicAuthNone
Request Body schema: application/x-www-form-urlencoded
insight_id
required
string <uuid>

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

Additional data provided by the user as key-value pairs (required when annotation=2)

device_id
string

Device identifier for tracking anonymous votes

Responses

Response samples

Content type
application/json
{
  • "status_code": 0,
  • "status": "string",
  • "description": "string"
}

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 or null
Default: null

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

count
integer or null [ 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

Prediction Management

Endpoints for managing and retrieving prediction data from various ML models.

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
}

Image Processing

Endpoints for processing and manipulating images, including cropping and running prediction models.

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://images.openfoodfacts.org/images/products/541/004/104/0807/3.jpg

The URL of the input image

y_min
number [ 0 .. 1 ]
Example: y_min=0.47795143723487854

The minimum y-coordinate for cropping, relative to the image height. We use relative coordinates, with (0, 0) being the upper left corner and (1, 1) being the lower right corner.

x_min
number [ 0 .. 1 ]
Example: x_min=0.5583494305610657

The minimum x-coordinate for cropping, relative to the image width. We use relative coordinates, with (0, 0) being the upper left corner and (1, 1) being the lower right corner.

y_max
number [ 0 .. 1 ]
Example: y_max=0.5653171539306641

The maximum y-coordinate for cropping, relative to the image height. We use relative coordinates, with (0, 0) being the upper left corner and (1, 1) being the lower right corner.

x_max
number [ 0 .. 1 ]
Example: x_max=0.6795185804367065

The maximum x-coordinate for cropping, relative to the image width. We use relative coordinates, with (0, 0) being the upper left corner and (1, 1) being the lower right corner.

Responses

Predict on images

Run image prediction models on product images

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

models
string
Example: models=nutrition-table,universal-logo-detector

Comma-separated list of model names to run

output_image_id
string

Image ID to store predictions for

Responses

Response samples

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

Image Management

Endpoints for managing and retrieving image data and metadata.

Get images

Retrieve images with optional filters

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
integer
Example: barcode=5410041040807

Filter by barcode value

with_predictions
boolean
Default: false

Filter images that have predictions

Responses

Response samples

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

Image Predictions

Get image predictions

Return image predictions based on various filters. The results can be filtered by model name, type, confidence, and more.

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 or null
Default: null

if True, only return image predictions that have associated logos (only valid for universal-logo-detector image predictions). If false, only return image predictions that have no associated logos. Otherwise, return all image predictions.

model_name
string
Example: model_name=universal-logo-detector

filter by name of the image predictor model

image_id
string
Example: image_id=1

filter by image ID. It should be a digit (raw images only), otherwise no result will be returned.

type
string
Example: type=object_detection

filter by type of the image predictor model

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
}

Import image predictions

Bulk import image predictions into the database

Request Body schema: application/json
required
Array of objects

Responses

Request samples

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

Logo Management

Endpoints for managing logo annotations, searching, and bulk operations on logos detected in product images.

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

Annotate multiple logos

Bulk annotate logos with type and value

Authorizations:
basicAuth
Request Body schema: application/json
required
Array of objects
server_type
object

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

Responses

Request samples

Content type
application/json
{
  • "annotations": [
    ],
  • "server_type": { }
}

Response samples

Content type
application/json
{
  • "annotated": 0
}

Bulk update logo annotations

Mass update logo annotations by changing type and value

query Parameters
source_type
required
string

Current logo type to update from

source_value
required
string

Current logo value to update from

target_type
required
string

New logo type to update to

target_value
required
string

New logo value to update to

Responses

Response samples

Content type
application/json
{
  • "updated": 0
}

Get logo details

Get details about a specific logo

path Parameters
logo_id
required
integer
Example: 1

The ID of the logo

Responses

Response samples

Content type
application/json
{ }

Update logo annotation

Update the type and value of a logo annotation

Authorizations:
basicAuth
path Parameters
logo_id
required
integer
Example: 1

The ID of the logo to update

Request Body schema: application/json
type
required
string non-empty

The type of the logo

value
string or null

The value/name of the logo

Responses

Request samples

Content type
application/json
{
  • "type": "string",
  • "value": "string"
}

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

Extract ingredient list from OCR

Extract and parse ingredient lists from OCR text

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

URL of the OCR JSON to process

aggregation_strategy
string
Default: "simple"
Enum: "simple" "max" "first"

Strategy for aggregating ingredient entities

model_version
string
Default: "1"

Version of the ingredient extraction model

Responses

Response samples

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

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

Predict nutritional information from a packaging image using the Nutri-Sight model.

The model takes an image and the OCR result (as a JSON file) obtained from Google Cloud Vision. For more information about the model, see the Nutri-Sight documentation.

query Parameters
image_url
string <uri>
Example: image_url=https://images.openfoodfacts.org/images/products/541/004/104/0807/3.jpg

The URL of the input image

ocr_url
string <uri>
Example: ocr_url=https://images.openfoodfacts.org/images/products/541/004/104/0807/3.json

The URL of the OCR JSON to use. The OCR must have been extracted using Google Cloud Vision, and be in the JSON format.

Responses

Response samples

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

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 language of a text

Predict the language of a text using a neural model. Use this POST version for long texts, as the GET version has a limit on the length of the text that can be provided in the query string.

Request Body schema: application/json
text
required
string

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

Request samples

Content type
application/json
{
  • "text": "hello world",
  • "k": 10,
  • "threshold": 0.01
}

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

k
integer >= 1
Default: 10

Number of language 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
{
  • "counts": [
    ],
  • "percent": [
    ],
  • "image_ids": [
    ]
}

System

Get API status

Check if the API is running

Responses

Response samples

Content type
application/json
{
  • "status": "running"
}

Get health check status

Check the health of all system components

Responses

Response samples

Content type
application/json
{
  • "message": { },
  • "status": 0,
  • "headers": { }
}

User Management

Endpoints for managing user data and statistics.

Get user statistics

Get annotation statistics for a specific user

path Parameters
username
required
string
Example: contributor

The username to get statistics for

Responses

Response samples

Content type
application/json
{
  • "count": {
    }
}

Annotation Management

Endpoints for managing annotation collections and metadata.

Get logo annotations

Retrieve logo annotations with optional filters

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
integer
Example: barcode=5410041040807

Filter by barcode value

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

types
string
Example: types=brand,label

Comma-separated list of annotation types to filter by

Responses

Response samples

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

Dataset

Get dataset information

Get information about the product dataset

Responses

Response samples

Content type
application/json
{
  • "etag": "string"
}

Update product dataset

Trigger an update of the product dataset

Responses

Batch Job

Import batch job results

Import batch job data into Robotoff database. This endpoint is secured and requires bearer authentication.

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.

batch_dir
required
string
Example: batch_dir=gs://bucket/path/to/batch/results

The directory path where batch job results are stored

Responses

Response samples

Content type
application/json
{
  • "status": "string"
}