Difference between revisions of "API/Write"
Jump to navigation
Jump to search
| Line 7: | Line 7: | ||
<big>The new version of the documentation is available here: | <big>The new version of the documentation is available here: | ||
| − | *[https://openfoodfacts.github.io/openfoodfacts-server/reference/api/ OpenAPI | + | * [https://openfoodfacts.github.io/api-documentation/ API V2 - Comprehensive but not OpenAPI compliant] - It contains uses cases for displaying a product, and letting your users add the data required to get the Nutri-Score, the NOVA classification, additives, and the Eco-Score. |
| + | * [https://openfoodfacts.github.io/openfoodfacts-server/reference/api/ API V2 - new OpenAPI documentation] - Work in Progress | ||
| + | * [https://openfoodfacts.github.io/openfoodfacts-server/reference/api-v3/ API V3 - new OpenAPI documentation] - Work in Progress | ||
</big> | </big> | ||
Revision as of 13:35, 8 December 2022
← Back to API (Required reading)
First of all, remember to do tests on https://world.openfoodfacts.net - login and password: off.
The new version of the documentation is available here:
- API V2 - Comprehensive but not OpenAPI compliant - It contains uses cases for displaying a product, and letting your users add the data required to get the Nutri-Score, the NOVA classification, additives, and the Eco-Score.
- API V2 - new OpenAPI documentation - Work in Progress
- API V3 - new OpenAPI documentation - Work in Progress
Status Codes
If the edit was successful
{
...
"status_verbose": "fields saved",
"status": 1
...
}
If there was an issue
Wrong password
HTML 200 code + an HTML page with a link to login
Authentication
Fields:
- user_id: string
- password: string
WARNING: If the password is not correct, the API will currently "silently" fail, both for image addition and product data addition (will return HTML 200 code + an html page with a link to login - example )
Anonymous contribution
- It is possible for new products (no anonymous modification is possible though, for obvious reasons)
- It is possible for adding images (as many as you like)
If you detect an error 200 (wrong password), please retry the query without user_id and password. That way the contribution will be accepted. Otherwise, the photo will get lost :(
Global account
If you want to avoid coding the detection of password errors, login stuff… you can create a global account for all your users.
You can create a global account to let the users of your app contribute. Please name it YourApp_app or something like that, so that we can spot it easily. Better yet, introduce yourself on Slack :-)
Manipulating photos for a product
Posting a new product
Do a GET request, otherwise you'll get
{
“status_verbose”: “no code or invalid code”,
“status”: 0
}Endpoint: https://world.openfoodfacts.org/cgi/product_jqm2.pl(Product post)(remember to do tests on world.openfoodfacts.net - login and password: "off")
Testing endpoint:https://world.openfoodfacts.net/cgi/product_jqm2.pl
Quick overview
- Var foodfact = { barcode : '0048151623426', name : 'Product name', energy: 500, energy_unit: "kJ", weight: 282 };
- Var postData = {
- Code : foodfact.barcode,
- User_id : "mesinfosnutritionelles",
- Password : "****",
- Product_name : foodfact.name?foodfact.name:foodfact.shop_label,
- Quantity : foodfact.weight?""+foodfact.weight+" g":undefined,
- Stores : "Walmart",
- Nutriment_energy :foodfact.energy,
- Nutriment_energy_unit :foodfact.energy_unit,
- Nutrition_data_per :"serving"
Status after save
{
"status_verbose": "fields saved",
"status": 1
}
Examples
(remember to do tests on world.openfoodfacts.net - login and password: off)
Query 1 : Unauthentified query
https://world.openfoodfacts.net/cgi/product_jqm2.pl?code=0048151623426&product_name=Maryland%20Choc%20Chip&quantity=230g&brands=Golden%20Cookies&nutriment_energy=450&nutriment_energy_unit=kJ&nutrition_data_per=serving&ingredients_text=Fortified%20wheat%20flour%2C%20Chocolate%20chips%20%2825%25%29%2C%20Sugar%2C%20Palm%20oil%2C%20Golden%20syrup%2C%20Whey%20and%20whey%20derivatives%20%28Milk%29%2C%20Raising%20agents%2C%20Salt%2C%20Flavouring&traces=Milk%2C+Soya%2C+Nuts%2C+Wheat
Result 2
https://uk.openfoodfacts.net/product/0072417136160/maryland-choc-chip
Query 2 : Authenticated query
https://world.openfoodfacts.org/cgi/product_jqm2.pl?code=0048151623426&user_id=usernameexample&password=*****&product_name=KIRI%20GOUTER%20280G%208%20PORTIONS&quantity=282%20g&stores=Intermarch%C3%A9&nutriment_energy=500&nutriment_energy_unit=kJ&nutrition_data_per=serving
Result 2
If credentials are correct
Standard success status, see above
If credentials are not correct
Will give you a responsive HTML login page.
See editing a product for details on fields
Posting several values for a field
When adding values, send to the field labels as comma separated values that are canonicalised and added to the _tags array
labels = "labelA, labelB"
Reading back, use labels_tags to get an array of labels
Editing an existing product
Posting additional photos
Type: POST
Endpoint: /cgi/product_image_upload.pl
Fields:
code: the barcodeimagefield: (front | ingredients | nutrition)
Please refer to the more complete: API/Write/Photos
Add more pictures without selecting them
- Imagefield: (other)
Select the Front picture
- Imgupload_front : your image file if imagefield:front
Select the Ingredients picture
- Imgupload_ingredients: your image file if imagefield:ingredients
Select the Nutrition Facts picture
- Imgupload_nutrition: your image file if imagefield:nutrition
Editing the product
Adding values to a field that is already filled
You just have to prefix add_ before the name of the field. Examples:
add_categories add_labels add_brands …
This adds a new value but doesn't delete the previous ones. Adding values doesn't need authentication but take it into account. Examples:
https://world.openfoodfacts.net/cgi/product_jqm2.pl?code=0048151621226&add_brands=Brand%202https://world.openfoodfacts.net/cgi/product_jqm2.pl?code=0048151621226&user_id=username&password=*****&add_brands=Brand%203
Give the barcode
code=072417136160
Add the brand
brands=Heinz
Add the name
product_name=Maryland%20Choc%20Chip
Add the quantity
quantity=230g
Add the packager code
emb_codes=EMB%2013330
Add the packaging type
packaging=Cardboard
Add the labels
labels=Vegan%2C%20Fat%20free
Add the Stores where bought
stores=Intermarch%C3%A9
Add the category
categories=Cookies
Add the best before date
expiration_date=
Add the link to the official webpage of the product
link=
Add the ingredients
ingredients_text=Fortified%20wheat%20flour%2C%20Chocolate%20chips%20%2825%25%29%2C%20Sugar%2C%20Palm%20oil%2C%20Golden%20syrup%2C%20Whey%20and%20whey%20derivatives%20%28Milk%29%2C%20Raising%20agents%2C%20Salt%2C%20Flavouring
Add ingredient traces
traces=Milk%2C+Soya%2C+Nuts%2C+Wheat
Add the main language
You can set the main language of the product.
lang=fr
(NOT LIVE YET) In the case of a multilingual product, you can specify the main language of the product, and you can then specify values and images for different languages by suffixing the language code to the other fields.
Add the nutrition facts
Indicate the absence of nutrition facts
no_nutrition_data=on (indicates if the nutrition facts are not indicated on the food label)
Add nutrition facts values, units and base
Define the basis for the values
nutrition_data_per=100g
OR
nutrition_data_per=serving
serving_size=38g
Input values and units
nutriment_energy=450
nutriment_energy_unit=kJ
Values
nutriment_energy nutriment_proteins nutriment_casein nutriment_serum-proteins nutriment_nucleotides nutriment_carbohydrates nutriment_sugars nutriment_sucrose nutriment_glucose nutriment_fructose nutriment_lactose nutriment_maltose nutriment_maltodextrins nutriment_starch nutriment_polyols nutriment_fat nutriment_saturated-fat nutriment_butyric-acid nutriment_caproic-acid nutriment_caprylic-acid nutriment_capric-acid nutriment_lauric-acid nutriment_myristic-acid nutriment_palmitic-acid nutriment_stearic-acid nutriment_arachidic-acid nutriment_behenic-acid nutriment_lignoceric-acid nutriment_cerotic-acid nutriment_montanic-acid nutriment_melissic-acid nutriment_monounsaturated-fat nutriment_polyunsaturated-fat nutriment_omega-3-fat nutriment_alpha-linolenic-acid nutriment_eicosapentaenoic-acid nutriment_docosahexaenoic-acid nutriment_omega-6-fat nutriment_linoleic-acid nutriment_arachidonic-acid nutriment_gamma-linolenic-acid nutriment_dihomo-gamma-linolenic-acid nutriment_omega-9-fat nutriment_oleic-acid nutriment_elaidic-acid nutriment_gondoic-acid nutriment_mead-acid nutriment_erucic-acid nutriment_nervonic-acid nutriment_trans-fat nutriment_cholesterol nutriment_fiber nutriment_salt nutriment_sodium nutriment_alcohol : % vol of alcohol nutriment_vitamin-a nutriment_vitamin-d nutriment_vitamin-e nutriment_vitamin-k nutriment_vitamin-c nutriment_vitamin-b1 nutriment_vitamin-b2 nutriment_vitamin-pp nutriment_vitamin-b6 nutriment_vitamin-b9 nutriment_vitamin-b12 nutriment_biotin nutriment_pantothenic-acid nutriment_silica nutriment_bicarbonate nutriment_potassium nutriment_chloride nutriment_calcium nutriment_phosphorus nutriment_iron nutriment_magnesium nutriment_zinc nutriment_copper nutriment_manganese nutriment_fluoride nutriment_selenium nutriment_chromium nutriment_molybdenum nutriment_iodine nutriment_caffeine nutriment_taurine nutriment_ph : pH (no unit)
Units
nutriment_energy_unit nutriment_proteins_unit nutriment_casein_unit nutriment_serum-proteins_unit nutriment_nucleotides_unit nutriment_carbohydrates_unit nutriment_sugars_unit nutriment_sucrose_unit nutriment_glucose_unit nutriment_fructose_unit nutriment_lactose_unit nutriment_maltose_unit nutriment_maltodextrins_unit nutriment_starch_unit nutriment_polyols_unit nutriment_fat_unit nutriment_saturated-fat_unit nutriment_butyric-acid_unit nutriment_caproic-acid_unit nutriment_caprylic-acid_unit nutriment_capric-acid_unit nutriment_lauric-acid_unit nutriment_myristic-acid_unit nutriment_palmitic-acid_unit nutriment_stearic-acid_unit nutriment_arachidic-acid_unit nutriment_behenic-acid_unit nutriment_lignoceric-acid_unit nutriment_cerotic-acid_unit nutriment_montanic-acid_unit nutriment_melissic-acid_unit nutriment_monounsaturated-fat_unit nutriment_polyunsaturated-fat_unit nutriment_omega-3-fat_unit nutriment_alpha-linolenic-acid_unit nutriment_eicosapentaenoic-acid_unit nutriment_docosahexaenoic-acid_unit nutriment_omega-6-fat_unit nutriment_linoleic-acid_unit nutriment_arachidonic-acid_unit nutriment_gamma-linolenic-acid_unit nutriment_dihomo-gamma-linolenic-acid_unit nutriment_omega-9-fat_unit nutriment_oleic-acid_unit nutriment_elaidic-acid_unit nutriment_gondoic-acid_unit nutriment_mead-acid_unit nutriment_erucic-acid_unit nutriment_nervonic-acid_unit nutriment_trans-fat_unit nutriment_cholesterol_unit nutriment_fiber_unit nutriment_salt_unit nutriment_sodium_unit nutriment_alcohol_unit : % vol of alcohol nutriment_vitamin-a_unit nutriment_vitamin-d_unit nutriment_vitamin-e_unit nutriment_vitamin-k_unit nutriment_vitamin-c_unit nutriment_vitamin-b1_unit nutriment_vitamin-b2_unit nutriment_vitamin-pp_unit nutriment_vitamin-b6_unit nutriment_vitamin-b9_unit nutriment_vitamin-b12_unit nutriment_biotin_unit nutriment_pantothenic-acid_unit nutriment_silica_unit nutriment_bicarbonate_unit nutriment_potassium_unit nutriment_chloride_unit nutriment_calcium_unit nutriment_phosphorus_unit nutriment_iron_unit nutriment_magnesium_unit nutriment_zinc_unit nutriment_copper_unit nutriment_manganese_unit nutriment_fluoride_unit nutriment_selenium_unit nutriment_chromium_unit nutriment_molybdenum_unit nutriment_iodine_unit nutriment_caffeine_unit nutriment_taurine_unit nutriment_ph_unit : pH (no unit)
Adding the alcohol % of wine
12% wine
nutriment_alcohol_unit=%25%20vol&nutriment_alcohol=12
Adding the carbon footprint
nutriment_carbon-footprint
nutriment_carbon-footprint_unit
Adding a comment to your edit
comment=Automated%20Edit