API/Read/Search

<Back to API/Read(Required reading)

Important

Please send a User-Agent HTTP Header with the name of the app/service querying, the version, system and a url if you have one, so that you are not blocked by mistake*

• e.g. User-Agent: CoolFoodApp - Android - Version 1.0 - https://coolfoodapp.com

Searching for products

Generic Search

Note that the search API caches results, and to get recent edits in your search results you must add `nocache=1` to the query parameters.

Core principle: Combine tags to get custom results

Combining tags is really powerful, letting you create thousands of custom APIs for your use case.

• https://world.openfoodfacts.org/packager-code/emb-35069c/brand/sojasun.json

Advanced Search

Query examples

https://world.openfoodfacts.org/cgi/search.pl?search_terms=coke&search_simple=1&jqm=1

https://world.openfoodfacts.org/cgi/search.pl?search_terms=banania&search_simple=1&action=process&json=1

https://world.openfoodfacts.org/cgi/search.pl?search_terms=banania&search_simple=1&action=process&xml=1

https://world.openfoodfacts.org/cgi/search.pl?search_terms=banania&search_simple=1&action=process&rss=1

Parameters

You can basically use all the parameters you'd use in a graphical advanced search on the site

search_url = "https://world.openfoodfacts.org/cgi/search.pl"
search_terms2 # search terms

# FIRST CRITERIA (TAG0)

tagtype_0
search_tag # choose a criterion...

# CRITERION
brands # brands
categories # categories
packaging # packaging
labels # labels
origins # origins of ingredients
manufacturing_places # manufacturing or processing places
emb_codes # packager codes
purchase_places # purchase places
stores # stores
countries # countries
additives # additives
allergens # allergens
traces # traces
nutrition_grades # Nutrition grades
states # states
	
# Contains or Not
tag_contains_0
contains
does_not_contain

# Value of Tag (free text)
tag_0

#additives 
additives 
without # without_additives
with # with_additives
indifferent # indifferent_additives

# Ingredients from palm oil
ingredients_from_palm_oil 
without
with
indifferent	

# Ingredients that may be from palm oil
ingredients_that_may_be_from_palm_oil
without
with
indifferent

#ingredients_from_or_that_may_be_from_palm_oi
ingredients_from_or_that_may_be_from_palm_oil
without
with
indifferent


# Nutrients

nutriment_0

search_nutriment # choose a nutriment...

energy # Energy
energy-from-fat # Energy from fat
fat # Fat
saturated-fat # Saturated fat
butyric-acid # Butyric acid (4:0)
caproic-acid # Caproic acid (6:0)
caprylic-acid # Caprylic acid (8:0)
capric-acid # Capric acid (10:0)
lauric-acid # Lauric acid (12:0)
myristic-acid # Myristic acid (14:0)
palmitic-acid # Palmitic acid (16:0)
stearic-acid # Stearic acid (18:0)
arachidic-acid # Arachidic acid (20:0)
behenic-acid # Behenic acid (22:0)
lignoceric-acid # Lignoceric acid (24:0)
cerotic-acid # Cerotic acid (26:0)
montanic-acid # Montanic acid (28:0)
melissic-acid # Melissic acid (30:0)
monounsaturated-fat # Monounsaturated fat
polyunsaturated-fat # Polyunsaturated fat
omega-3-fat # Omega 3 fatty acids
alpha-linolenic-acid # Alpha-linolenic acid / ALA (18:3 n-3)
eicosapentaenoic-acid # Eicosapentaenoic acid / EPA (20:5 n-3)
docosahexaenoic-acid # Docosahexaenoic acid / DHA (22:6 n-3)
omega-6-fat # Omega 6 fatty acids
linoleic-acid # Linoleic acid / LA (18:2 n-6)
arachidonic-acid # Arachidonic acid / AA / ARA (20:4 n-6)
gamma-linolenic-acid # Gamma-linolenic acid / GLA (18:3 n-6)
dihomo-gamma-linolenic-acid # Dihomo-gamma-linolenic acid / DGLA (20:3 n-6)
omega-9-fat # Omega 9 fatty acids
oleic-acid # Oleic acid (18:1 n-9)
elaidic-acid # Elaidic acid (18:1 n-9)
gondoic-acid # Gondoic acid (20:1 n-9)
mead-acid # Mead acid (20:3 n-9)
erucic-acid # Erucic acid (22:1 n-9)
nervonic-acid # Nervonic acid (24:1 n-9)
trans-fat # Trans fat
cholesterol # Cholesterol
carbohydrates # Carbohydrate
sugars # Sugars
sucrose # Sucrose
glucose # Glucose
fructose # Fructose
lactose # Lactose
maltose # Maltose
maltodextrins # Maltodextrins
starch # Starch
polyols # Sugar alcohols (Polyols)
fiber # Dietary fiber
proteins # Proteins
casein # casein
serum-proteins # Serum proteins
nucleotides # Nucleotides
salt # Salt
sodium # Sodium
alcohol # Alcohol
vitamin-a # Vitamin A
beta-carotene # Beta carotene
vitamin-d # Vitamin D
vitamin-e # Vitamin E
vitamin-k # Vitamin K
vitamin-c # Vitamin C (ascorbic acid)
vitamin-b1 # Vitamin B1 (Thiamin)
vitamin-b2 # Vitamin B2 (Riboflavin)
vitamin-pp # Vitamin B3 / Vitamin PP (Niacin)
vitamin-b6 # Vitamin B6 (Pyridoxin)
vitamin-b9 # Vitamin B9 (Folic acid / Folates)
vitamin-b12 # Vitamin B12 (cobalamin)
biotin # Biotin
pantothenic-acid # Pantothenic acid / Pantothenate (Vitamin B5)
silica # Silica
bicarbonate # Bicarbonate
potassium # Potassium
chloride # Chloride
calcium # Calcium
phosphorus # Phosphorus
iron # Iron
magnesium # Magnesium
zinc # Zinc
copper # Copper
manganese # Manganese
fluoride # Fluoride
selenium # Selenium
chromium # Chromium
molybdenum # Molybdenum
iodine # Iodine
caffeine # Caffeine
taurine # Taurine
ph # pH
fruits-vegetables-nuts # Fruits, vegetables and nuts (minimum)
collagen-meat-protein-ratio # Collagen/Meat protein ratio (maximum)
cocoa # Cocoa (minimum)
chlorophyl # Chlorophyl
carbon-footprint # Carbon footprint / CO2 emissions
nutrition-score-fr # Experimental nutrition score
nutrition-score-uk # Nutrition score - UK

# Comparison of nutrients
# Nutriment to compare
nutriment_compare_0

# Operator
lt # less than
lte # less than or equal
gt # greater than
gte # greater than or equal
eq # equal to
		
# Value to compare the nutrients to
nutriment_value_0

# Output
sort_by # sort_by
unique_scans_n # Popularity
product_name # Product name
created_t # Add date
last_modified_t # Edit date


# Results per page	
page_size # page_size
20 # 20
50 # 50
100 # 100
250 # 250
500 # 500
1000 # 1000

#Pagination
page=1

#Format
json=1
xml=1
#to search results pages on the web site to get results in a jQuery Mobile format.
jqm=1

Linked Data

Link to Wikipedia and Wikidata

• Whenever possible, Open Food Facts entities are linked to Wikidata, and in turn to Wikipedia. What this means is that you get access to a trove of additional encyclopedic knowledge about food. You can for instance get: Wikipedia articles about Camembert, the translation of salt in many languages, the molecular structure of a cosmetic ingredient…
  
• We provide the Wikidata QID, which is an unambiguous, stable and reliable identifier for a concept that will be useful to actually retrieve info from Wikipedia and Wikidata.

Example

https://world.openfoodfacts.net/categories.json

{"linkeddata":{"wikidata:en":"Q40050"},"url":"https://world.openfoodfacts.net/category/beverages","name":"Beverages","id":"en:beverages","products":14196}

Beverages >> https://world.openfoodfacts.org/category/beverages >> Q40050 >> https://www.wikidata.org/wiki/Q40050
As you see, you'll get a beautiful image, information about the Quality label… As Wikidata is a Wiki, the knowledge you'll be able to retrieve will increase over time.

Retrieving info from Wikipedia and Wikidata

You can use the Wikipedia and Wikidata APIs to get the information you want

• https://www.wikidata.org/wiki/Wikidata:Data_access
• https://en.wikipedia.org/w/api.php

Examples of things you can do

• Provide more context and more information about a specific Product, a Category of products, a Quality label, a Geography, a Brand, a Packaging material, an ingredient…
• Perform checks or computations by mixing Wikidata information and Open Food Facts information (and possibly other APIs)