{"id":19670094,"url":"https://github.com/openfoodfacts/openfoodfacts-apirestpython","last_synced_at":"2025-07-25T22:39:14.401Z","repository":{"id":980892,"uuid":"36238120","full_name":"openfoodfacts/openfoodfacts-apirestpython","owner":"openfoodfacts","description":"Python API for Open Food Facts (using a DB dump)","archived":false,"fork":false,"pushed_at":"2024-10-01T06:54:09.000Z","size":157,"stargazers_count":59,"open_issues_count":7,"forks_count":15,"subscribers_count":13,"default_branch":"develop","last_synced_at":"2024-10-29T22:38:12.018Z","etag":null,"topics":["food","food-products","hacktoberfest","python-api"],"latest_commit_sha":null,"homepage":"https://openfoodfacts.github.io/OpenFoodFacts-APIRestPython","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/openfoodfacts.png","metadata":{"funding":{"patreon":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"lfx_crowdfunding":null,"open_collective":"openfoodfacts-server","github":"openfoodfacts","custom":"https://donate.openfoodfacts.org"},"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-05-25T15:17:57.000Z","updated_at":"2024-10-14T13:27:36.000Z","dependencies_parsed_at":"2023-07-05T21:02:08.641Z","dependency_job_id":"bbdba81e-0f8f-4ebd-9adb-d626b01cc53e","html_url":"https://github.com/openfoodfacts/openfoodfacts-apirestpython","commit_stats":{"total_commits":117,"total_committers":8,"mean_commits":14.625,"dds":0.6239316239316239,"last_synced_commit":"2e4ebde03ebc2e4005a7579c7ea1b66049b85a3a"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openfoodfacts%2Fopenfoodfacts-apirestpython","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openfoodfacts%2Fopenfoodfacts-apirestpython/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openfoodfacts%2Fopenfoodfacts-apirestpython/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openfoodfacts%2Fopenfoodfacts-apirestpython/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/openfoodfacts","download_url":"https://codeload.github.com/openfoodfacts/openfoodfacts-apirestpython/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246620224,"owners_count":20806722,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["food","food-products","hacktoberfest","python-api"],"created_at":"2024-11-11T17:04:04.384Z","updated_at":"2025-04-02T09:07:26.751Z","avatar_url":"https://github.com/openfoodfacts.png","language":"Python","funding_links":["https://opencollective.com/openfoodfacts-server","https://github.com/sponsors/openfoodfacts","https://donate.openfoodfacts.org"],"categories":[],"sub_categories":[],"readme":"# Open Food Facts API Rest Python\n\nOFF API provides programmatic access to Open Food Facts functionality and content.\u003cbr/\u003e\n\n[![Deploy](https://www.herokucdn.com/deploy/button.svg)](https://heroku.com/deploy?template=https://github.com/openfoodfacts/OpenFoodFacts-APIRestPython)\n\nTo try the API : https://openfoodfacts-api.herokuapp.com/ \u003cbr/\u003e\nOr if you want to try in localhost, see below.\n\nThe API is [REST API](https://en.wikipedia.org/wiki/Representational_State_Transfer \"RESTful\").\nCurrently, return format for all endpoints is [JSON](https://json.org/ \"JSON\").\n\n## Status\n\n\n[![Project Status](http://opensource.box.com/badges/active.svg)](http://opensource.box.com/badges)\n[![Build Status](https://travis-ci.org/openfoodfacts/OpenFoodFacts-APIRestPython.svg?branch=master)](https://travis-ci.org/openfoodfacts/OpenFoodFacts-APIRestPython)\n[![Average time to resolve an issue](https://isitmaintained.com/badge/resolution/openfoodfacts/OpenFoodFacts-APIRestPython.svg)](https://isitmaintained.com/project/openfoodfacts/OpenFoodFacts-APIRestPython \"Average time to resolve an issue\")\n[![Percentage of issues still open](https://isitmaintained.com/badge/open/openfoodfacts/OpenFoodFacts-APIRestPython.svg)](https://isitmaintained.com/project/openfoodfacts/OpenFoodFacts-APIRestPython \"Percentage of issues still open\")\n\n## What is this repository for?\n\nThis piece of software’s main goals are:\n* To make it easy to retrieve data using HTTP requests\n* To provide filters in the API\n* To provide custom filters\n\n\n## Setup for localhost\n\n* Install python 3\n* Install mongodb\n* Install pip\n* Install requirements: `$ pip install -r requirements.txt`\n* Download the database from : https://world.openfoodfacts.org/data/openfoodfacts-mongodbdump.tar.gz\n* Import to local mongodb: `$ mongorestore -d off -c products /foldertobsonfile/products.bson`\n* Launch api: `$ python3 runApiRESTServer.py`\n* That's all!\n\n## Documentation\n### How to use it?\n\nSimple filter: `/products?origins=United Kingdom` \u003cbr/\u003e\nComplex filter: `/products?nutrition_grade_fr=a\u0026origins=United Kingdom` \u003cbr/\u003e\nFor arrays, a “.” will be used as a separator like so: `/products?nutrient_levels.salt=low`\nSearchs can be inexact like :`/products?ingredients_text=beef`\u003cbr/\u003e\nIt will retrieve tags like “beef braising steak”, “beef steak”...\n\n/!\\ By default the objects will be sorted by `created_t` in order to have the most important objects first\n\nURL to query                   | Description\n------------------------------ | ---------------------------\n\u003ccode\u003eGET\u003c/code\u003e `/product/\u003cbarcode\u003e`           | Get a product by barcode eg. `/product/737628064502`\n\u003ccode\u003eGET\u003c/code\u003e `/products/brands`             | Return a list of `Brands`. If you want to query brands, to do for example an autocomplete field in ajax, query the API like: `/products/brands?query=Auch` or `/products/brands?query=Sains`.\n\u003ccode\u003eGET\u003c/code\u003e `/products/categories`         | Return a list of `Categories`. If you want to query categories, to do for example an autocomplete field in ajax, query the API like: `/products/categories?query=Ric` or `/products/categories?query=plant`.\n\u003ccode\u003eGET\u003c/code\u003e `/products/countries`          | Return a list of `Countries`. If you want to query countries, to do for example an autocomplete field in ajax, query the API like: `/products/countries?query=Fra` or `/products/countries?query=Aus`.\n\u003ccode\u003eGET\u003c/code\u003e `/products/additives`          | Return a list of `Additives`. If you want to query additives, to do for example an autocomplete field in ajax, query the API like: `/products/additives?query=Citric` or `/products/additives?query=acid`.\n\u003ccode\u003eGET\u003c/code\u003e `/products/allergens`          | Return a list of `Allergens`. If you want to query allergens, to do for example an autocomplete field in ajax, query the API like: `/products/allergens?query=milk` or `/products/allergens?query=oil`.\n\n### Options\n\nField         | Value by default | Value type\n------------- | ---------------- | ---------\nlimit=        | 50               | limit the number of products returned\nskip=         | 0                | skips the specified number of products returned\ncount=        | 0                | if 1 then returns the number of rows\nshort=        | 0                | Filters rows retrieved, make it faster for lists for example, if 1 columns projection on `code`, `lang` and `product_name`\nq=            | none             | search text on indexed fields\n\n### Indexed fields\n\nSome fields are described here: https://world.openfoodfacts.org/data/data-fields.txt\n\n### Example\n**Request**\n\n    GET /product/737628064502\n\n**Return**\n``` json\n{\n   \"status_verbose\":\"product found\",\n   \"status\":1,\n   \"product\":{\n      \"last_edit_dates_tags\":[\n         \"2012-12-11\",\n         \"2012-12\",\n         \"2012\"\n      ],\n      \"labels_hierarchy\":[\n         \"en:gluten-free\"\n      ],\n      \"_id\":\"737628064502\",\n      \"categories_hierarchy\":[\n         \"en:Rice Noodles\"\n      ],\n      \"pnns_groups_1\":\"unknown\",\n      \"states_tags\":[\n         \"en:to-be-checked\",\n         \"en:complete\",\n         \"en:nutrition-facts-completed\",\n         \"en:ingredients-completed\",\n         \"en:expiration-date-to-be-completed\",\n         \"en:characteristics-completed\",\n         \"en:photos-validated\",\n         \"en:photos-uploaded\"\n      ],\n      \"checkers_tags\":[\n      ],\n      \"labels_tags\":[\n         \"en:gluten-free\"\n      ],\n      \"image_small_url\":\"https://world.openfoodfacts.org/images/products/737/628/064/502/front.6.200.jpg\",\n      \"code\":\"737628064502\",\n      \"additives_tags_n\":null,\n      \"traces_tags\":[\n         \"peanuts\"\n      ],\n      \"lang\":\"en\",\n      \"photographers\":[\n         \"andre\"\n      ],\n      \"generic_name\":\"Rice Noodles\",\n      \"ingredients_that_may_be_from_palm_oil_tags\":[\n      ],\n      \"old_additives_tags\":[\n         \"en:e330\"\n      ],\n      \"_keywords\":[\n         \"thailand\",\n         \"stir-fry\",\n         \"kitchen\",\n         \"thai\",\n         \"free\",\n         \"gluten\",\n         \"rice\",\n         \"noodle\"\n      ],\n      \"rev\":15,\n      \"editors\":[\n         \"\",\n         \"thierrym\",\n         \"manu1400\",\n         \"andre\"\n      ],\n      \"interface_version_created\":\"20120622\",\n      \"emb_codes\":\"\",\n      \"max_imgid\":\"5\",\n      \"additives_tags\":[\n         \"en:e330\"\n      ],\n      \"emb_codes_orig\":\"\",\n      \"informers_tags\":[\n         \"andre\",\n         \"manu1400\",\n         \"thierrym\"\n      ],\n      \"nutrient_levels_tags\":[\n         \"脂肪-in-moderate-quantity\",\n         \"饱和脂肪-in-low-quantity\",\n         \"糖-in-high-quantity\",\n         \"食盐-in-high-quantity\"\n      ],\n      \"photographers_tags\":[\n         \"andre\"\n      ],\n      \"additives_n\":1,\n      \"pnns_groups_2_tags\":[\n         \"unknown\"\n      ],\n      \"unknown_nutrients_tags\":[\n      ],\n      \"packaging_tags\":[\n         \"cellophane\",\n         \"carton\"\n      ],\n      \"nutriments\":{\n         \"sodium\":\"0.629\",\n         \"sugars\":10,\n         \"carbohydrates_unit\":\"g\",\n         \"fat_unit\":\"g\",\n         \"proteins_unit\":\"g\",\n         \"nutrition-score-fr_100g\":15,\n         \"fat\":7,\n         \"proteins_serving\":7,\n         \"sodium_serving\":0.629,\n         \"salt\":1.59766,\n         \"proteins\":7,\n         \"nutrition-score-fr\":15,\n         \"sugars_unit\":\"g\",\n         \"fat_serving\":7,\n         \"sodium_unit\":\"mg\",\n         \"sugars_100g\":\"12.8\",\n         \"saturated-fat_unit\":\"g\",\n         \"sodium_100g\":0.806,\n         \"saturated-fat_serving\":1,\n         \"fiber_unit\":\"g\",\n         \"energy\":1297,\n         \"energy_unit\":\"kcal\",\n         \"sugars_serving\":10,\n         \"carbohydrates_100g\":70.5,\n         \"nutrition-score-uk\":15,\n         \"proteins_100g\":8.97,\n         \"fiber_serving\":0,\n         \"carbohydrates_serving\":55,\n         \"energy_serving\":1297,\n         \"fat_100g\":\"8.97\",\n         \"saturated-fat_100g\":\"1.28\",\n         \"nutrition-score-uk_100g\":15,\n         \"fiber\":0,\n         \"salt_serving\":1.59766,\n         \"salt_100g\":\"2.05\",\n         \"carbohydrates\":55,\n         \"fiber_100g\":0,\n         \"energy_100g\":1660,\n         \"saturated-fat\":1\n      },\n      \"countries_tags\":[\n         \"en:france\"\n      ],\n      \"ingredients_from_palm_oil_tags\":[\n      ],\n      \"emb_codes_tags\":[\n      ],\n      \"brands_tags\":[\n         \"thai-kitchen\"\n      ],\n      \"purchase_places\":\"\",\n      \"pnns_groups_2\":\"unknown\",\n      \"countries_hierarchy\":[\n         \"en:france\"\n      ],\n      \"traces\":\"Peanuts\",\n      \"categories\":\"Rice Noodles\",\n      \"ingredients_text\":\"RICE NOODLES (RICE, WATER), SEASONING PACKET (PEANUT, SUGAR, SALT, CORN STARCH, SPICES [CHILI, CINNAMON, PEPPER, CUMIN, CLOVE], HYDRDLYZED SOY PROTEIN, GREEN ONIONS, CITRIC ACID, PEANUT OIL, SESAME OIL, NATURAL FLAVOR).  \",\n      \"created_t\":1345799269,\n      \"product_name\":\"Stir-Fry Rice Noodles\",\n      \"ingredients_from_or_that_may_be_from_palm_oil_n\":0,\n      \"creator\":\"andre\",\n      \"no_nutrition_data\":null,\n      \"serving_size\":\"78 g\",\n      \"completed_t\":1355184837,\n      \"last_modified_by\":\"thierrym\",\n      \"new_additives_n\":1,\n      \"origins\":\"Thailand\",\n      \"stores\":\"\",\n      \"nutrition_grade_fr\":\"d\",\n      \"nutrient_levels\":{\n         \"salt\":\"high\",\n         \"fat\":\"moderate\",\n         \"sugars\":\"high\",\n         \"saturated-fat\":\"low\"\n      },\n      \"stores_tags\":[\n      ],\n      \"id\":\"737628064502\",\n      \"countries\":\"France\",\n      \"purchase_places_tags\":[\n      ],\n      \"interface_version_modified\":\"20120622\",\n      \"fruits-vegetables-nuts_100g_estimate\":0,\n      \"sortkey\":1355184837,\n      \"last_modified_t\":1355184837,\n      \"nutrition_score_debug\":\" -- energy 4 + sat-fat 1 + fr-sat-fat-for-fats 0 + sugars 2 + sodium 8 - fruits 0% 0 - fiber 0 - proteins 5 -- fsa 15 -- fr 15\",\n      \"countries.20131227\":null,\n      \"correctors_tags\":[\n         \"andre\",\n         \"thierrym\"\n      ],\n      \"correctors\":[\n         \"andre\",\n         \"thierrym\"\n      ],\n      \"new_additives_debug\":\"lc: en -  [ rice-noodles -\u003e en:rice-noodles  ]  [ rice -\u003e en:rice  ]  [ water -\u003e en:water  ]  [ seasoning-packet -\u003e en:seasoning-packet  ]  [ peanut -\u003e en:peanut  ]  [ sugar -\u003e en:sugar  ]  [ salt -\u003e en:salt  ]  [ corn-starch -\u003e en:corn-starch  ]  [ spices-chili -\u003e en:spices-chili  ]  [ cinnamon -\u003e en:cinnamon  ]  [ pepper -\u003e en:pepper  ]  [ cumin -\u003e en:cumin  ]  [ clove -\u003e en:clove  ]  [ hydrdlyzed-soy-protein -\u003e en:hydrdlyzed-soy-protein  ]  [ green-onions -\u003e en:green-onions  ]  [ citric-acid -\u003e en:e330  -\u003e exists  ]  [ peanut-oil -\u003e en:peanut-oil  ]  [ sesame-oil -\u003e en:sesame-oil  ]  [ natural-flavor -\u003e en:natural-flavor  ] \",\n      \"brands\":\"Thai Kitchen\",\n      \"ingredients_tags\":[\n         \"rice-noodles\",\n         \"seasoning-packet\",\n         \"\",\n         \"rice\",\n         \"water\",\n         \"peanut\",\n         \"sugar\",\n         \"salt\",\n         \"corn-starch\",\n         \"spices\",\n         \"chili\",\n         \"cinnamon\",\n         \"pepper\",\n         \"cumin\",\n         \"clove\",\n         \"hydrdlyzed-soy-protein\",\n         \"green-onions\",\n         \"citric-acid\",\n         \"peanut-oil\",\n         \"sesame-oil\",\n         \"natural-flavor\"\n      ],\n      \"new_additives_tags\":[\n         \"en:e330\"\n      ],\n      \"states\":\"en:to-be-checked, en:complete, en:nutrition-facts-completed, en:ingredients-completed, en:expiration-date-to-be-completed, en:characteristics-completed, en:photos-validated, en:photos-uploaded\",\n      \"informers\":[\n         \"andre\",\n         \"manu1400\",\n         \"thierrym\"\n      ],\n      \"entry_dates_tags\":[\n         \"2012-08-24\",\n         \"2012-08\",\n         \"2012\"\n      ],\n      \"nutrition_grades_tags\":[\n         \"d\"\n      ],\n      \"packaging\":\"Cellophane,Carton\",\n      \"serving_quantity\":78,\n      \"origins_tags\":[\n         \"thailand\"\n      ],\n      \"nutrition_data_per\":\"serving\",\n      \"labels\":\"gluten free\",\n      \"cities_tags\":[\n      ],\n      \"emb_codes_20141016\":\"\",\n      \"categories_tags\":[\n         \"en:rice-noodles\"\n      ],\n      \"quantity\":\"155 g\",\n      \"expiration_date\":\"\",\n      \"states_hierarchy\":[\n         \"en:to-be-checked\",\n         \"en:complete\",\n         \"en:nutrition-facts-completed\",\n         \"en:ingredients-completed\",\n         \"en:expiration-date-to-be-completed\",\n         \"en:characteristics-completed\",\n         \"en:photos-validated\",\n         \"en:photos-uploaded\"\n      ],\n      \"ingredients_that_may_be_from_palm_oil_n\":0,\n      \"ingredients_from_palm_oil_n\":0,\n      \"image_url\":\"https://world.openfoodfacts.org/images/products/737/628/064/502/front.6.400.jpg\",\n      \"ingredients\":[\n         {\n            \"text\":\"RICE NOODLES\",\n            \"id\":\"rice-noodles\",\n            \"rank\":1\n         },\n         {\n            \"text\":\"SEASONING PACKET\",\n            \"id\":\"seasoning-packet\",\n            \"rank\":2\n         },\n         {\n            \"text\":\".\",\n            \"id\":\"\",\n            \"rank\":3\n         },\n         {\n            \"text\":\"RICE\",\n            \"id\":\"rice\"\n         },\n         {\n            \"text\":\"WATER\",\n            \"id\":\"water\"\n         },\n         {\n            \"text\":\"PEANUT\",\n            \"id\":\"peanut\"\n         },\n         {\n            \"text\":\"SUGAR\",\n            \"id\":\"sugar\"\n         },\n         {\n            \"text\":\"SALT\",\n            \"id\":\"salt\"\n         },\n         {\n            \"text\":\"CORN STARCH\",\n            \"id\":\"corn-starch\"\n         },\n         {\n            \"text\":\"SPICES\",\n            \"id\":\"spices\"\n         },\n         {\n            \"text\":\"CHILI\",\n            \"id\":\"chili\"\n         },\n         {\n            \"text\":\"CINNAMON\",\n            \"id\":\"cinnamon\"\n         },\n         {\n            \"text\":\"PEPPER\",\n            \"id\":\"pepper\"\n         },\n         {\n            \"text\":\"CUMIN\",\n            \"id\":\"cumin\"\n         },\n         {\n            \"text\":\"CLOVE\",\n            \"id\":\"clove\"\n         },\n         {\n            \"text\":\"HYDRDLYZED SOY PROTEIN\",\n            \"id\":\"hydrdlyzed-soy-protein\"\n         },\n         {\n            \"text\":\"GREEN ONIONS\",\n            \"id\":\"green-onions\"\n         },\n         {\n            \"text\":\"CITRIC ACID\",\n            \"id\":\"citric-acid\"\n         },\n         {\n            \"text\":\"PEANUT OIL\",\n            \"id\":\"peanut-oil\"\n         },\n         {\n            \"text\":\"SESAME OIL\",\n            \"id\":\"sesame-oil\"\n         },\n         {\n            \"text\":\"NATURAL FLAVOR\",\n            \"id\":\"natural-flavor\"\n         }\n      ],\n      \"lc\":\"en\",\n      \"pnns_groups_1_tags\":[\n         \"unknown\"\n      ],\n      \"checkers\":[\n      ],\n      \"complete\":1\n   },\n   \"code\":\"737628064502\"\n}\n```\n\n## Creators\n\n**Scot Scriven**\n- \u003chttps://github.com/itchix\u003e\n\n## Copyright and license\n\n    Copyright 2015 Scriven Scot\n\n    Licensed under the Apache License, Version 2.0 (the \"License\");\n    you may not use this file except in compliance with the License.\n    You may obtain a copy of the License at\n\n        https://www.apache.org/licenses/LICENSE-2.0\n\n    Unless required by applicable law or agreed to in writing, software\n    distributed under the License is distributed on an \"AS IS\" BASIS,\n    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n    See the License for the specific language governing permissions and\n    limitations under the License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenfoodfacts%2Fopenfoodfacts-apirestpython","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopenfoodfacts%2Fopenfoodfacts-apirestpython","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenfoodfacts%2Fopenfoodfacts-apirestpython/lists"}