API/Read: Difference between revisions
No edit summary |
No edit summary |
||
| Line 1: | Line 1: | ||
[[Category:Developer]] [[Category:API]] | [[Category:Developer]] | ||
[[API| ← Back to API]] (required read) | [[Category:API]] | ||
[[API|← Back to API]] (required read) | |||
'''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. | '''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. | ||
| Line 6: | Line 8: | ||
Example: <code>UserAgent: CoolFoodApp - Android - Version 1.0 - https://coolfoodapp.com</code> | Example: <code>UserAgent: CoolFoodApp - Android - Version 1.0 - https://coolfoodapp.com</code> | ||
== 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: | 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: | ||
* https://world.openfoodfacts.org/data (all data) | * https://world.openfoodfacts.org/data (all data) | ||
* https://fr.openfoodfacts.org/data (data for that country) | * https://fr.openfoodfacts.org/data (data for that country) | ||
=== CSV API === | |||
The character that separates fields is | |||
The character that separates fields is (tabulation). | |||
=== Field reference == | ==== Encoding ==== | ||
The [[fields used]] in the api | |||
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 | https://world.openfoodfacts.org/data/data-fields.txt | ||
== JSON interface == | |||
=== Pagination of results === | === 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. | 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: | To move from page to page: | ||
| Line 30: | Line 40: | ||
https://fr-en.openfoodfacts.org/category/pizzas/2.json | https://fr-en.openfoodfacts.org/category/pizzas/2.json | ||
</pre> | </pre> | ||
=== Countries and Language of the Response === | === 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). | |||
* An alternative to avoid dealing with local languages is to specify the language in the subdomain: https://fr-en.openfoodfacts.org/category/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. | By default, the country code (cc) and language of the interface (lc) are set through the subdomain. | ||
In general they follow the scheme: | |||
<pre>https://<cc>-<lc>.openfoodfacts.org</pre> | |||
==== Examples ==== | |||
# https://world.openfoodfacts.org --> cc = world, lc = en (default language for the "country") | # https://world.openfoodfacts.org --> cc = world, lc = en (default language for the "country") | ||
# https://fr.openfoodfacts.org --> cc = fr (France), lc = fr (French) | # https://fr.openfoodfacts.org --> cc = fr (France), lc = fr (French) | ||
| Line 46: | Line 67: | ||
# https://ch.openfoodfacts.org --> cc = ch (Switzerland), lc = de (German, set as main language for Switzerland) | # https://ch.openfoodfacts.org --> cc = ch (Switzerland), lc = de (German, set as main language for Switzerland) | ||
# https://ch-fr.openfoodfacts.org --> cc = ch, lc = fr (French) | # https://ch-fr.openfoodfacts.org --> cc = ch, lc = fr (French) | ||
=== Over-riding Country code (cc) and Language of the interface (lc) using cc and lc parameters === | |||
If you pass ?cc=us and/or &lc=it, it will set the country to US and the language to Italian | If you pass ?cc=us and/or &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. | -> if you just pass cc, the lc will be the one set in the subdomain. | ||
| Line 57: | Line 80: | ||
If the results include links to products, those links will use a new subdomain that corresponds to the overrides. | If the results include links to products, those links will use a new subdomain that corresponds to the overrides. | ||
== Viewing a product == | |||
[[API/Read/Product]] | [[API/Read/Product]] | ||
== Searching for products == | |||
[[API/Read/Search]] | [[API/Read/Search]] | ||
Revision as of 21:10, 31 May 2019
← Back to API (required read)
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.
Example: UserAgent: CoolFoodApp - Android - Version 1.0 - https://coolfoodapp.com
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:
- https://world.openfoodfacts.org/data (all data)
- https://fr.openfoodfacts.org/data (data for that country)
CSV API
The character that separates fields is (tabulation).
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).
- An alternative to avoid dealing with local languages is to specify the language in the subdomain: https://fr-en.openfoodfacts.org/category/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
- https://world.openfoodfacts.org --> cc = world, lc = en (default language for the "country")
- https://fr.openfoodfacts.org --> cc = fr (France), lc = fr (French)
- https://jp.openfoodfacts.org --> cc = jp (Japan), lc = ja (Japanese)
- https://ch.openfoodfacts.org --> cc = ch (Switzerland), lc = de (German, set as main language for Switzerland)
- https://ch-fr.openfoodfacts.org --> cc = ch, lc = fr (French)
Over-riding Country code (cc) and Language of the interface (lc) using cc and lc parameters
If you pass ?cc=us and/or &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 = fr --> 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.