{"id":15698205,"url":"https://github.com/nelson-gon/pyfdc","last_synced_at":"2025-05-09T01:13:27.948Z","repository":{"id":53817196,"uuid":"226465545","full_name":"Nelson-Gon/pyfdc","owner":"Nelson-Gon","description":"A python interface to FoodDataCentral","archived":false,"fork":false,"pushed_at":"2022-10-11T18:22:47.000Z","size":314,"stargazers_count":6,"open_issues_count":3,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-05-09T01:13:21.639Z","etag":null,"topics":["agriculture","api","api-documentation","api-query","api-wrapper","food","food-data","health","health-data","nutrients","nutrition","nutrition-information","nutritionfacts","pip","python","python3","requests","rest","usda-nutrient-database"],"latest_commit_sha":null,"homepage":"https://pyfdc.readthedocs.io/en/latest/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Nelson-Gon.png","metadata":{"files":{"readme":"README.md","changelog":"changelog.md","contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":".github/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-12-07T06:18:16.000Z","updated_at":"2023-12-07T09:34:27.000Z","dependencies_parsed_at":"2022-08-21T17:40:45.469Z","dependency_job_id":null,"html_url":"https://github.com/Nelson-Gon/pyfdc","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Nelson-Gon%2Fpyfdc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Nelson-Gon%2Fpyfdc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Nelson-Gon%2Fpyfdc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Nelson-Gon%2Fpyfdc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Nelson-Gon","download_url":"https://codeload.github.com/Nelson-Gon/pyfdc/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253171272,"owners_count":21865297,"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":["agriculture","api","api-documentation","api-query","api-wrapper","food","food-data","health","health-data","nutrients","nutrition","nutrition-information","nutritionfacts","pip","python","python3","requests","rest","usda-nutrient-database"],"created_at":"2024-10-03T19:23:52.061Z","updated_at":"2025-05-09T01:13:27.921Z","avatar_url":"https://github.com/Nelson-Gon.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# pyfdc: A python interface to FoodDataCentral\n[![PyPI version fury.io](https://badge.fury.io/py/pyfdc.svg)](https://pypi.python.org/pypi/pyfdc/)\n[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.3764453.svg)](https://doi.org/10.5281/zenodo.3764453)\n[![Project Status](http://www.repostatus.org/badges/latest/active.svg)](http://www.repostatus.org/#active) \n[![Codecov](https://codecov.io/gh/Nelson-Gon/pyfdc/branch/master/graph/badge.svg)](https://codecov.io/gh/Nelson-Gon/pyfdc?branch=master)\n![Test-Package](https://github.com/Nelson-Gon/pyfdc/workflows/Test-Package/badge.svg)\n[![PyPI license](https://img.shields.io/pypi/l/pyfdc.svg)](https://pypi.python.org/pypi/pyfdc/)\n[![Documentation Status](https://readthedocs.org/projects/pyfdc/badge/?version=latest)](https://pyfdc.readthedocs.io/en/latest/?badge=latest)\n[![Total Downloads](https://pepy.tech/badge/pyfdc)](https://pepy.tech/project/pyfdc)\n[![Monthly Downloads](https://pepy.tech/badge/pyfdc/month)](https://pepy.tech/project/pyfdc)\n[![Weekly Downloads](https://pepy.tech/badge/pyfdc/week)](https://pepy.tech/project/pyfdc)\n[![Maintenance](https://img.shields.io/badge/Maintained%3F-yes-green.svg)](https://GitHub.com/Nelson-Gon/pyfdc/graphs/commit-activity)\n[![GitHub last commit](https://img.shields.io/github/last-commit/Nelson-Gon/pyfdc.svg)](https://github.com/Nelson-Gon/pyfdc/commits/master)\n[![GitHub issues](https://img.shields.io/github/issues/Nelson-Gon/pyfdc.svg)](https://GitHub.com/Nelson-Gon/pyfdc/issues/)\n[![GitHub issues-closed](https://img.shields.io/github/issues-closed/Nelson-Gon/pyfdc.svg)](https://GitHub.com/Nelson-Gon/pyfdc/issues?q=is%3Aissue+is%3Aclosed)\n\n\n\n**Installation**\n\nThe simplest way to install the latest release is as follows:\n\n```shell\npip install pyfdc\n\n```\n\nTo install the development version:\n\n\nOpen the Terminal/CMD/Git bash/shell and enter\n\n```shell\n\npip install git+https://github.com/Nelson-Gon/pyfdc.git\n\n# or for the less stable dev version\npip install git+https://github.com/Nelson-Gon/pyfdc.git@develop\n\n```\n\nOtherwise:\n\n```shell\n# clone the repo\ngit clone git@github.com:Nelson-Gon/pyfdc.git\ncd pyfdc\npython3 -m pip install . \n\n```\n\n\n\n**Sample usage**\n\n\nThere are two ways to use `pydfc`. In script mode, one does the following:\n\n```shell\npython -m pyfdc --method \"info\" --phrase \"cheese\" | head\n#/pyfdc/pyfdc/pyfdc.py:109: UserWarning: No target_fields were provided, returning fdc_id, ingredients, and description.\n#  warn(\"No target_fields were provided, returning fdc_id, ingredients, and description.\")\n#     fdc_id  ...                                   description\n#0    816524  ...                                        CHEESE\n#1   1463368  ...                                        CHEESE\n#2   1597534  ...                                        CHEESE\n#3   1653804  ...                                        CHEESE\n#4   1660793  ...                                        CHEESE\n#5   1497465  ...                                        CHEESE\n#6   1465399  ...                                        CHEESE\n#7    515803  ...                                        CHEESE\n#8    500370  ...                                        CHEESE\n#\n\n\n\n```\n\nThe above uses the `get_food_info` method. To use, the `get_food_details` method, one simply sets method to \"details\" \nand provides the target FoodDataCentral ID. \n\n```shell\n python -m pyfdc --method \"details\" --phrase 816524  --fields \"nutrients\"\n \n#      id number                                      name   rank unitName\n#0   1004    204                         Total lipid (fat)    800        g\n#1   1257    605                  Fatty acids, total trans  15400        g\n#2   1079    291                      Fiber, total dietary   1200        g\n#3   1003    203                                   Protein    600        g\n#4   1005    205               Carbohydrate, by difference   1110        g\n#5   1110    324  Vitamin D (D2 + D3), International Units   8650       IU\n#6   1008    208                                    Energy    300     kcal\n#7   2000    269              Sugars, total including NLEA   1510        g\n#8   1089    303                                  Iron, Fe   5400       mg\n#9   1087    301                               Calcium, Ca   5300       mg\n#10  1258    606              Fatty acids, total saturated   9700        g\n#11  1093    307                                Sodium, Na   5800       mg\n#12  1253    601                               Cholesterol  15700       mg\n\n```\n\n\n```python\n\nfrom pyfdc.pyfdc import FoodDataCentral\nfrom pyfdc.utils import set_api_key\n\n```\n\n**Set session api key**\n\nTo avoid providing an api key for each call, one can set a session api key as follows:\n\n```python\n\nset_api_key(\"my_api_key_here\")\n\n\n```\n\n\n**Key Features**\n\nThere is one major class `FoodDataCentral`. \nSee the [changelog](https://github.com/Nelson-Gon/pyfdc/blob/master/changelog.md) \nfor more details.:\n\nTo instantiate an object:\n\n```python\nmy_search = FoodDataCentral()\n```\n\nTo get details about foods for a given search term, one can do the following:\n\n```python\n\nmy_search.get_food_info(search_phrase=\"cheese\").head(6)\n\n```\n\nThe above will result in the following output:\n\n```shell\n\n#\n#UserWarning: No target_fields were provided, returning fdc_id, ingredients, and description.\n#    fdc_id                                        ingredients description\n#0   816524  BELLAVITANO CHEESE (PASTEURIZED MILK, CHEESE C...      CHEESE\n#1  1210322  BELLAVITANO CHEESE (PASTEURIZED MILK, CHEESE C...      CHEESE\n#2  1291586  CHEDDAR CHEESE (PASTEURIZED MILK, CHEESE CULTU...      CHEESE\n#3  1305389   PASTEURIZED COWS' MILK, SALT, CULTURES, ENZYMES.      CHEESE\n#4  1361608  CULTURED PASTEURIZED MILK, SALT, NON-ANIMAL EN...      CHEESE\n#5  1420013  FRESH PART-SKIM COW'S MILK, CHEESE CULTURE SAL...      CHEESE\n\n\n```\n\n\nIn the above, we got a warning message because we used defaults out-of-the-box. To customize, we can set \nthe `target_fields` we wish to have.\n\n```shell\nmy_search.get_food_info(search_phrase=\"cheese\", target_fields=[\"description\"]).head(4)\n\n# description\n# 0      CHEESE\n# 1      CHEESE\n# 2      CHEESE\n# 3      CHEESE\n```\n\n\n\n\n\nTo get full details about a given `fdcId`, one can do the following:\n\n```shell\n\nmy_search.get_food_details(168977)\n\n```\n\nThis will give us the following output(truncated):\n\n```shell\n# UserWarning: No target_field was provided, returning low level results.\n#           0                                                  1\n#0                      fdcId                                             168977\n#1                description  Agutuk, meat-caribou (Alaskan ice cream) (Alas...\n#2            publicationDate                                           4/1/2019\n#3              foodNutrients  [{'nutrient': {'id': 2045, 'number': '951', 'n...\n#4                   dataType                                          SR Legacy\n\n```\n\nThe above is a low-level result that may be useful for development purpises. \n\nTo get nutrient details:\n\n```shell\n\nmy_search.get_food_details(fdc_id= 496446,target_field=\"nutrients\")\n\n# nutrient.id nutrient.unitName                   nutrient.name  \\\n#0         1089                mg                        Iron, Fe   \n#1         1258                 g    Fatty acids, total saturated   \n#2         1253                mg                     Cholesterol   \n#3         1162                mg  Vitamin C, total ascorbic acid   \n#4         1087                mg                     Calcium, Ca   \n#5         1104                IU                   Vitamin A, IU   \n#                  foodNutrientDerivation.description       id  amount  \\\n#0  Calculated from a daily value percentage per s...  3992103    3.39   \n#1  Calculated from a daily value percentage per s...  3992107    0.47   \n#2  Calculated from a daily value percentage per s...  3992106    0.00   \n#3  Calculated from a daily value percentage per s...  3992105    0.00   \n#4  Calculated from a daily value percentage per s...  3992102  118.00   \n#5  Calculated from a daily value percentage per s...  3992104    0.00   \n#  nutrient.number  nutrient.rank  \n#0             303           5400  \n#1             606           9700  \n#2             601          15700  \n#3             401           6300 \n\n```\n\nOne can also get label nutrients (if they exist):\n\n```shell \nmy_search.get_food_details(504905, target_field=\"label_nutrients\")\n\n#    fat  saturatedFat  transFat  cholesterol  sodium  ...  calcium  iron  potassium  addedSugar  calories\n#0  15.0           4.5       0.0         84.5  1060.0  ...     80.6  1.08       70.2        1.04       179\n\n#[1 rows x 14 columns]\n```\n\n**Credit**\n\n1. **Original Food Data Central API**\n\nThe API interfaced is available [here](https://fdc.nal.usda.gov/api-guide.html)\n\n**Thank you very much**. \n\n\u003e To report any issues, suggestions or improvement, please do so \nat [issues](https://github.com/Nelson-Gon/pyfdc/issues). \n\n\u003e “Before software can be reusable it first has to be usable.” – Ralph Johnson\n\n---\n\nIf you would like to cite this work, please use:\n\nNelson Gonzabato(2020) pyfdc: A python interface to FoodDataCentral, https://github.com/Nelson-Gon/pyfdc\n\nBibTex:\n\n```shell\n@misc{Gonzabato2021,\n  author = {Gonzabato, N},\n  title = {pyfdc: A python interface to FoodDataCentral},\n  year = {2021},\n  publisher = {GitHub},\n  journal = {GitHub repository},\n  howpublished = {\\url{https://github.com/Nelson-Gon/pyfdc}},\n  commit = {20923d9dbea9dcf1b5cba741625b01f6637a6d7b}\n} \n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnelson-gon%2Fpyfdc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnelson-gon%2Fpyfdc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnelson-gon%2Fpyfdc/lists"}