|
|
| (3 intermediate revisions by 2 users not shown) |
| Line 1: |
Line 1: |
| | __NOINDEX__ |
| [[Category:Developer]] [[Category:API]] | | [[Category:Developer]] [[Category:API]] |
| The API (Application Programming Interface) is the way an application can enter in dialogue with Open Food Facts application server. | | The API (Application Programming Interface) is the way an application can enter in dialogue with Open Food Facts application server. |
|
| |
|
| It can be used to retrieve data (search), read or write information (see disclaimer, in production, this should correspond to a user scan).
| | All information about the API can be found [https://openfoodfacts.github.io/openfoodfacts-server/api/ in the documentation]. |
| | |
| ⚠ '''Disclaimer''':
| |
| | |
| If you are not in a production scenario, think about using the pre-production instance at https://world.openfoodfacts.net.
| |
| | |
| If you want to use data from open food facts for research, for heavy duty, or to get performance insurance, you may duplicate the database: see https://world.openfoodfacts.org/data
| |
| | |
| == Search API v2 ==
| |
| A new search api (work in progress) is available, which is easier to use. See [[Open Food Facts Search API Version 2]]
| |
| | |
| = NEW version of the documentation =
| |
| | |
| The new version of the documentation is available here:
| |
| | |
| * [https://openfoodfacts.github.io/openfoodfacts-server/reference/api.html new version of the documentation as OpenAPI 3.1 (still a work in progress)] ([https://github.com/openfoodfacts/openfoodfacts-server/tree/main/docs/reference/ source])
| |
| | |
| * Previous [https://openfoodfacts.github.io/api-documentation version of the documentation]
| |
| | |
| We have many SDKs at the bottom of the page, and we also have official implementations for Android, iPhone (and Flutter) that you can draw inspiration from.
| |
| | |
| = Previous version of the documentation =
| |
| | |
| === Notice for API users ===
| |
| # You are very welcome to use the API for production cases, as long as '''1 API call = 1 real scan by a user'''.
| |
| # <span style="color:#d33">'''If you need all the database, download it directly from the data page, do ''NOT'' scrape the API'''</span>
| |
| # Please tell us (contact@openfoodfacts.org or in the #API channel) what you build with the API, it's always great to see new reuses come to life :-)
| |
| | |
| === 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 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 ===
| |
| 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 ===
| |
| 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 information, see [[API/Read]]
| |
| | |
| === Technical details ===
| |
| * You can do READ operations using the production server.
| |
| * You should use the SSL version of the API. <code>https://world.openfoodfacts.org</code>
| |
| * '''Please send a UserAgent 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. <code>UserAgent: MyFoodApp - Android - Version 1.0 - https://myfoodapp.example.com</code>)
| |
| | |
| == WRITE operations ==
| |
| For more information, see [[API/Write]]
| |
| | |
| === Use cases ===
| |
| * You can add photos and information to Open Food Facts using the API.
| |
| ** Letting your users add new products by uploading photos is the most common use case.
| |
| ** Several apps already enable more advanced editing. Gamification would be welcome.
| |
| * The official mobile apps can use some help.
| |
| | |
| === A few things ===
| |
| * '''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.
| |
| * 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.dev (ask for the password on Slack)
| |
| | |
| === Conventions for the API ===
| |
| * fields that end with _t are dates in the UNIX timestamp format (number of seconds since Jan 1st 1970)
| |
| * fields that end with _datetime are dates in the iso8601 format: yyyy-mm-ddThh:mn:ssZ
| |
| * fields that end with _tags are comma separated list of tags (e.g. categories_tags is the set of normalized tags computer from the categories field)
| |
| * 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
| |
| * keys must match BSON syntax, and may not contain `.` or `$`.
| |
| | |
| === Ready made code you can use in your app ===
| |
| React Native: https://github.com/openfoodfacts/openfoodfacts-react-native
| |
| | |
| == SDKs ==
| |
| We have projects to create SDKs for major platforms. If you'd like to help out, [https://slack.openfoodfacts.org please join the dedicated Slack discussion channels] or open an issue on the existing repository.
| |
| | |
| It is important that SDK support both read and write operations, and evolve with the API.
| |
| | |
| * [[API/Android|Android SDK]] - The official app used to be coded in Java and is now in Kotlin. Extraction into a reusable library would be welcome.
| |
| * 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]] - https://github.com/openfoodfacts/openfoodfacts-java
| |
| * [[API/Javascript|JavaScript SDK]] - We don't have a vanilla Javascript SDK right now
| |
| * Dart - https://github.com/openfoodfacts/openfoodfacts-dart
| |
| * Flutter (official app) - https://github.com/openfoodfacts/smooth-app
| |
| * Kotlin (official app) - https://github.com/openfoodfacts/openfoodfacts-androidapp - The official app has recently been Kotlinized. (Help to turn it into a reusable library would be welcome)
| |
| * Laravel package - https://github.com/openfoodfacts/openfoodfacts-laravel
| |
| * [[API/Javascript/NodeJS|NodeJS SDK]] - https://github.com/openfoodfacts/openfoodfacts-nodejs
| |
| * [[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]]
| |
| * React Native SDK https://github.com/openfoodfacts/openfoodfacts-react-native (Help to turn it into a reusable library would be welcome)
| |
| * [[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]] - The official app is coded in Swift. https://github.com/openfoodfacts/openfoodfacts-ios Extraction into a Swift library would be welcome.
| |
| 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, using the easy API/SDK.
| |
| | |
| Please join us on the Slack channel to discuss the legal and technical side of things :-) (https://slack.openfoodfacts.org)
| |
| | |
| == Roadmap ==
| |
| | |
| * Publishing the API on a faster server
| |
| * Having a CI pipeline from the source repository to the published documentation
| |
| * Deprecating documentation on the wiki for good.
| |
| * Setting up a process to keep the API updated.
| |
| | |
| For the API revamp, see [[API/Roadmap]]. Please note that the above goals are our priority right now (making the current API work better for everyone).
| |
| | |
| == 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]
| |
| (For documentation issues, see below)
| |
| === Keeping the documentation up to date with the live API ===
| |
| * Project that tracks what we have to document: https://github.com/openfoodfacts/api-documentation/issues
| |
| | |
| === Known bugs ===
| |
| * General bugs: https://github.com/openfoodfacts/openfoodfacts-server/issues
| |
| * API bugs: https://github.com/openfoodfacts/openfoodfacts-server/labels/api
| |
| * API milestone: https://github.com/openfoodfacts/openfoodfacts-server/milestone/8
| |
| | |
| === Yet-Undocumented APIs ===
| |
| * https://github.com/openfoodfacts/api-documentation
| |
| | |
| == Sister projects ==
| |
| === Open Pet Food Facts ===
| |
| Open Pet Food Facts behaves just like Open Food Facts. Behaviours may change over time, as we tweak it.
| |
| * https://world.openpetfoodfacts.org/api/v0/product/20106836.json
| |
| | |
| === Open Beauty Facts ===
| |
| [[API/OpenBeautyFacts]]
| |
| | |
| === Open Products Facts ===
| |
| Open Products Facts behaves mostly like Open Food Facts. Behaviours may change over time, as we tweak it.
| |