Difference between revisions of "API"

From Open Food Facts wiki
Jump to navigation Jump to search
Line 73: Line 73:
 
=== Warning ===
 
=== Warning ===
 
* Some products are incomplete.  
 
* 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.
+
* '''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
 
* When doing averages, computations… filter incomplete products to avoid issues
 
* Assume the data is not reliable until the product is marked as complete.
 
* 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.
+
* '''In general, ensure the user exercises maintains caution (for allergens…) and be upfront about possible risks.'''
 
 
  
 
== Read API ==
 
== Read API ==

Revision as of 10:47, 17 November 2018


Introduction

Current status of the API

Getting help with the API

You can ask for help on using the API in this API channel on Slack. Join us to discuss your use case and get help/code from other devs.

How to test the API

READ operations

Technical details
  • You can do READ operations using production
  • You should now use the SSL version of the API. The unsecure version WILL be deprecated :-)
https://ssl-api.openfoodfacts.org
Licence

Open Food Facts is under the OdBL licence (database) and CC-BY-SA (pictures). That has a couple of legal implications. Please join us on the Slack channel to discuss them.

WRITE operations

Use cases
  • 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.
    • 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.net (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

Language Bindings

SDKs

We have projects to create SDKs for major platforms. If you'd like to help out, please join the dedicated Slack channels.

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.

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

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.

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.