API/Read: Difference between revisions

From Open Food Facts wiki
No edit summary
 
(5 intermediate revisions by 3 users not shown)
Line 4: Line 4:
[[API|← Back to API]] (required read)
[[API|← Back to API]] (required read)


=== The new version of the documentation is available here:
== Use the API ==
* [https://openfoodfacts.github.io/api-documentation Latest version of the documentation] ===
To use the read API, please check out the [https://openfoodfacts.github.io/openfoodfacts-server/api/ API documentation] and [https://openfoodfacts.github.io/openfoodfacts-server/api/ref-v2/#get-/api/v2/product/-barcode- how to read product data]
 
'''Please send a User-Agent 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.
 
Example: <code>User-Agent: CoolFoodApp - Android - Version 1.0 - https://theurlofthesiteofyourcoolfoodapp.com</code>


== Downloading static data ==
== Downloading static data ==
Line 21: Line 17:


The character that separates fields is  (tabulation).
The character that separates fields is  (tabulation).
For an example on how to import it in postgres, see https://iderr.github.io/p/week-1-new-project-on-openfoodfacts/


==== Encoding ====
==== Encoding ====

Latest revision as of 09:10, 15 August 2024


← Back to API (required read)

Use the API

To use the read API, please check out the API documentation and how to read product data

Downloading static data

It is recommended to use the live API to get fresh data about products, the minute they are uploaded to the database. However, in some cases, you may need a snapshot. They are available at:

CSV API

The character that separates fields is (tabulation).

For an example on how to import it in postgres, see https://iderr.github.io/p/week-1-new-project-on-openfoodfacts/

Encoding

The file encoding is Unicode UTF-8.

MongoDB dump

Field reference

The fields used in the api are: https://world.openfoodfacts.org/data/data-fields.txt

JSON interface

Pagination of results

If you're looking for all products within a facet (eg: https://fr-en.openfoodfacts.org/category/pizzas.json), you'll only have the 1st page. To move from page to page:

https://fr-en.openfoodfacts.org/category/pizzas/1.json
https://fr-en.openfoodfacts.org/category/pizzas/2.json

Countries and Language of the Response

You can either use the global (https://world.openfoodfacts.org, https://ssl-api.openfoodfacts.org) or local (https://fr.openfoodfacts.org, https://en.openfoodfacts.org, …) domains for your API queries.

A few things to note

  • If you use a country subdomain instead of world, you get products for that country only, which might change the language but also the name of the fields. In that case you need to use the local language.

(e.g. https://fr.openfoodfacts.org/categorie/pizzas.json).

Country code (cc) and Language of the interface (lc)

By default, the country code (cc) and language of the interface (lc) are set through the subdomain.

In general they follow the scheme:

https://<cc>-<lc>.openfoodfacts.org

Examples

  1. https://world.openfoodfacts.org --> cc = world, lc = en (default language for the "country")
  2. https://fr.openfoodfacts.org --> cc = fr (France), lc = fr (French)
  3. https://jp.openfoodfacts.org --> cc = jp (Japan), lc = ja (Japanese)
  4. https://ch.openfoodfacts.org --> cc = ch (Switzerland), lc = de (German, set as main language for Switzerland)
  5. https://ch-fr.openfoodfacts.org --> cc = ch, lc = fr (French)

Overriding Country code (cc) and Language of the interface (lc) using cc and lc parameters

You can pass the field cc (e.g. ?cc=us) and/or the field lc (e.g. ?lc=it) to customize the results.

For example, if you pass ?cc=us and &lc=it, it will set the country to US and the language to Italian; if you just pass cc, the lc will be the one set in the subdomain.

e.g. world.openfoodfacts.org?cc=frc -> cc = fr, lc = en (default language of world)


The cc affects which results are returned. cc = fr -> you get only products with France listed in the countries where sold field.

The lc affects the language in which results will come back.

If the results include links to products, those links will use a new subdomain that corresponds to the overrides.

Viewing a product

Have a look at: API/Read/Product

Searching for products

Have a look at: API/Read/Search