72
edits
Changes
Jump to navigation
Jump to search
Line 2:
Line 2: − + + + + + + + + + + − * Currently the API is used internally for the official Open Food Facts mobile applications (iOS, Android, Windows, and we need help !) and by hundreds of reuses on various topics (Nutrition, sport…) and platforms (iOS, Android…), but does not yet follow good practices in API design.+ − * It is also used by several applications and while not yet stable, doesn't change much.+ − * You can have a look at the source code of the app+ − ** https://github.com/openfoodfacts/cordova-app/blob/master/www/off.js+ − ** https://github.com/openfoodfacts/cordova-app/blob/master/www/index.html+ − * '''Anyone with Swagger (or equivalent knowledge) willing to help us document the API is most welcome :-)'''+ + − + + + + + − === How to test the API ===+ − ==== READ operations ====+ − ===== Technical details =====+ − + − − − ** e.g. UserAgent: CoolFoodApp - Android - Version 1.0 - https://coolfoodapp.com − ===== Licence ===== − Open Food Facts is under the OdBL licence (database) and CC-BY-SA (pictures). That has a couple of legal implications: in short: mention Open Food Facts as the source of the data, do not mix with other product databases (since you are then required to release them under OdBL, at your own legal risk if you didn't actually own them), share any additions under the OdBL, back to the community. Please join us on the Slack channel to discuss the legal and technical side of things :-) (https://slack.openfoodfacts.org) − ==== WRITE operations ====+ + − ===== Use cases =====+ Line 34:
Line 44: − ===== A few things =====+ − + − + Line 46:
Line 56: − === Language Bindings=== − * [[API/Android|Android bindings]] − * [[API/C sharp|C# bindings]] - https://github.com/Albert-Le5/openfoodfacts-csharp ; https://github.com/aberteau/OpenFoodFacts4Net − * [[API/Go|Go bindings]] - https://github.com/openfoodfacts/openfoodfacts-go − * [[API/Java|Java bindings]] − * [[API/Javascript|JS bindings]] − * [[API/Javascript/NodeJS|NodeJS bindings]] − * [[API/Perl|Perl bindings]] − * [[API/PHP|PHP bindings]] - https://github.com/openfoodfacts/openfoodfacts-php − * [[API/Python|Python bindings]] - https://github.com/openfoodfacts/openfoodfacts-python (LIVE API) - https://github.com/openfoodfacts/OpenFoodFacts-APIRestPython (Local Dump) − * [[API/R|R bindings]] − * [[API/Ruby|Ruby bindings]] - https://github.com/openfoodfacts/openfoodfacts-ruby - gem install openfoodfacts - https://github.com/openfoodfacts/openbeautyfacts-ruby - gem install openbeautyfacts − * [[API/Scala|Scala bindings]] − * [[API/Swift|Swift bindings]] − * Please help us bring Open Food Facts to your favorite language by contributing bindings − === SDKs ===+ + + + + + + + + + + + + + + + + + + + + + + + + − === Roadmap ===+ − === Bugs ===+ − ==== Reporting bugs ====+ − * Do not hesitate to file a bug if you find an issue in the API, or need an improvement.+ − ==== Known bugs ====+ + + + + − === Warning === − * Some products are incomplete. − * '''You should ensure your UX tells the final user that the product is not complete, encourage them to exercise caution and/or help complete the product.''' − * When doing averages, computations… filter incomplete products to avoid issues − * Assume the data is not reliable until the product is marked as complete. − * '''In general, ensure the user exercises maintains caution (for allergens…) and be upfront about possible risks.''' − − == Read API == − Please look at [[API/Read]] − − == Write API == − − Please look at [[API/Write]] Line 95:
Line 105: − −
no edit summary
== Introduction ==
== Introduction ==
=== If you need all the database, download it directly from the data page, do NOT scrape the API ===
=== Notice for API users ===
<span style="color:#d33">'''If you need all the database, download it directly from the data page, do ''NOT'' scrape the API'''</span>
=== Before using the API ===
* Some products are incomplete.
* '''You should ensure your UX tells the final user that the product is not complete, encourage them to exercise caution and/or help complete the product.'''
* When doing averages, computations… filter incomplete products to avoid issues
* Assume the data is not reliable until the product is marked as complete.
* '''In general, ensure the user exercises maintains caution (for allergens…) and be upfront about possible risks.'''
* <span style="color:#d33">'''By using any part of the API you have read and understood the [[#License|license]].'''</span>
=== Current status of the API ===
=== Current status of the API ===
Currently the API is used internally for the official Open Food Facts mobile applications (iOS, Android, Windows, and we need help!) and by hundreds of reuses on various topics (Nutrition, sport…) and platforms (iOS, Android…), but does not yet follow good practices in API design.
It is also used by several applications and while not yet stable, doesn't change much.
You can have a look at the source code of the apps ([[Mobile_App]])
'''Anyone with Swagger (or equivalent knowledge) willing to help us document the API is most welcome :-)'''
=== Getting help with the API ===
=== Getting help with the API ===
You can ask for help on using the API in this [https://openfoodfacts.slack.com/messages/api/ API channel on Slack]. Join us to discuss your use case and get help/code from other devs.
You can ask for help on using the API in the [https://openfoodfacts.slack.com/messages/api/ #api channel on Slack]. Join us to discuss your use case and get help/code from other devs.
== READ operations ==
For more details please look at [[API/Read]]
=== Technical details ===
* You can do READ operations using production server.
* You should use the SSL version of the API. <code>https://world.openfoodfacts.org</code>
* You can do READ operations using production
* '''Please send a UserAgent HTTP Header''' with the name of the app/service querying, the version, system and an URL if you have one, so that you are not blocked by mistake (e.g. <code>UserAgent: CoolFoodApp - Android - Version 1.0 - https://coolfoodapp.com</code>)
* You should now use the SSL version of the API. <pre>https://world.openfoodfacts.org</pre>
* '''Please send a UserAgent HTTP Header with the name of the app/service querying, the version, system and an url if you have one''', so that you are not blocked by mistake*
== WRITE operations ==
Please look at [[API/Write]]
=== Use cases ===
* You can add photos and informations to Open Food Facts using the API.
* You can add photos and informations to Open Food Facts using the API.
** Letting your users add new products by uploading photos is the most common use case.
** Letting your users add new products by uploading photos is the most common use case.
* The official mobile apps can use some help.
* The official mobile apps can use some help.
=== A few things ===
* Do join the API channel if you intend on using WRITE
* '''Do''' join the API channel if you intend on using WRITE
* Do not send copyrighted photos or information using the API. Everything you send is OdBL for the data, and CC-BY-SA for the pictures. If those are not yours (eg from scraping), you bear all the legal consequences.
* '''Do not''' send copyrighted photos or information using the API. Everything you send is OdBL for the data, and CC-BY-SA for the pictures. If those are not yours (eg from scraping), you bear all the legal consequences.
* You can create a global account for your app if you don't want to implement Open Food Facts user creation in your app right now. Please report it in #api so that it can be monitored for errors.
* You can create a global account for your app if you don't want to implement Open Food Facts user creation in your app right now. Please report it in #api so that it can be monitored for errors.
* You should do all your test edits on https://world.openfoodfacts.net (ask for the password on Slack)
* You should do all your test edits on https://world.openfoodfacts.net (ask for the password on Slack)
* fields that end with a language 2 letter code (e.g. fr for French) is the set of tags in that language
* fields that end with a language 2 letter code (e.g. fr for French) is the set of tags in that language
* fields that end with _100g correspond to the amount of a nutriment (in g) for 100 g or 100 ml of product
* fields that end with _100g correspond to the amount of a nutriment (in g) for 100 g or 100 ml of product
== SDKs ==
We have projects to create SDKs for major platforms. If you'd like to help out, please join the dedicated Slack channels.
We have projects to create SDKs for major platforms. If you'd like to help out, please join the dedicated Slack channels.
* [[API/Android|Android SDK]]
* [[API/C sharp|C# SDK]] - https://github.com/Albert-Le5/openfoodfacts-csharp ; https://github.com/aberteau/OpenFoodFacts4Net
* [[API/Go|Go SDK]] - https://github.com/openfoodfacts/openfoodfacts-go
* [[API/Java|Java SDK]]
* [[API/Javascript|JS SDK]]
* [[API/Javascript/NodeJS|NodeJS SDK]]
* [[API/Perl|Perl SDK]]
* [[API/PHP|PHP SDK]] - https://github.com/openfoodfacts/openfoodfacts-php
* [[API/Python|Python SDK]] - https://github.com/openfoodfacts/openfoodfacts-python (LIVE API) - https://github.com/openfoodfacts/OpenFoodFacts-APIRestPython (Local Dump)
* [[API/R|R SDK]]
* [[API/Ruby|Ruby SDK]] - https://github.com/openfoodfacts/openfoodfacts-ruby OR gem install openfoodfacts - https://github.com/openfoodfacts/openbeautyfacts-ruby OR gem install openbeautyfacts
* [[API/Scala|Scala SDK]]
* [[API/Swift|Swift SDK]]
Please help us bring Open Food Facts to your favorite language by contributing to SDK!
== Licence ==
Open Food Facts is under the [https://opendatacommons.org/licenses/odbl/ OdBL licence] (database) and [https://creativecommons.org/licenses/by-sa/3.0 CC-BY-SA] (pictures). That has a couple of legal implications, in short:
* Mention Open Food Facts as the source of the data;
* Do not mix with other product databases (since you are then required to release them under OdBL, at your own legal risk if you didn't actually own them);
* Share any additions under the OdBL, back to the community.
Please join us on the Slack channel to discuss the legal and technical side of things :-) (https://slack.openfoodfacts.org)
== Roadmap ==
[[API/Roadmap]]
[[API/Roadmap]]
== Bugs ==
=== Reporting bugs ===
Do not hesitate to file a bug if you find an issue in the API, or need an improvement!
You can fill in the issue report[https://github.com/openfoodfacts/openfoodfacts-server/issues/new here on GitHub]
=== Known bugs ===
* General bugs: https://github.com/openfoodfacts/openfoodfacts-server/issues
* General bugs: https://github.com/openfoodfacts/openfoodfacts-server/issues
* API bugs: https://github.com/openfoodfacts/openfoodfacts-server/labels/api
* API bugs: https://github.com/openfoodfacts/openfoodfacts-server/labels/api
* API milestone: https://github.com/openfoodfacts/openfoodfacts-server/milestone/8
* API milestone: https://github.com/openfoodfacts/openfoodfacts-server/milestone/8
== Sister projects ==
== Sister projects ==
=== Open Beauty Facts ===
=== Open Beauty Facts ===
[[API/OpenBeautyFacts]]
[[API/OpenBeautyFacts]]
=== Open Products Facts ===
=== Open Products Facts ===
Open Products Facts behaves mostly like Open Food Facts. Behaviours may change over time, as we tweak it.
Open Products Facts behaves mostly like Open Food Facts. Behaviours may change over time, as we tweak it.