Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/nelson-gon/pyfdc
A python interface to FoodDataCentral
https://github.com/nelson-gon/pyfdc
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
Last synced: 3 months ago
JSON representation
A python interface to FoodDataCentral
- Host: GitHub
- URL: https://github.com/nelson-gon/pyfdc
- Owner: Nelson-Gon
- License: mit
- Created: 2019-12-07T06:18:16.000Z (about 5 years ago)
- Default Branch: master
- Last Pushed: 2022-10-11T18:22:47.000Z (over 2 years ago)
- Last Synced: 2024-10-10T09:35:03.944Z (4 months ago)
- 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
- Language: Python
- Homepage: https://pyfdc.readthedocs.io/en/latest/
- Size: 307 KB
- Stars: 6
- Watchers: 2
- Forks: 1
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Changelog: changelog.md
- Contributing: .github/CONTRIBUTING.md
- License: LICENSE
- Code of conduct: .github/CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# pyfdc: A python interface to FoodDataCentral
[](https://pypi.python.org/pypi/pyfdc/)
[](https://doi.org/10.5281/zenodo.3764453)
[](http://www.repostatus.org/#active)
[](https://codecov.io/gh/Nelson-Gon/pyfdc?branch=master)
[](https://pypi.python.org/pypi/pyfdc/)
[](https://pyfdc.readthedocs.io/en/latest/?badge=latest)
[](https://pepy.tech/project/pyfdc)
[](https://pepy.tech/project/pyfdc)
[](https://pepy.tech/project/pyfdc)
[](https://GitHub.com/Nelson-Gon/pyfdc/graphs/commit-activity)
[](https://github.com/Nelson-Gon/pyfdc/commits/master)
[](https://GitHub.com/Nelson-Gon/pyfdc/issues/)
[](https://GitHub.com/Nelson-Gon/pyfdc/issues?q=is%3Aissue+is%3Aclosed)
**Installation**
The simplest way to install the latest release is as follows:
```shell
pip install pyfdc
```
To install the development version:
Open the Terminal/CMD/Git bash/shell and enter
```shell
pip install git+https://github.com/Nelson-Gon/pyfdc.git
# or for the less stable dev version
pip install git+https://github.com/Nelson-Gon/pyfdc.git@develop
```
Otherwise:
```shell
# clone the repo
git clone [email protected]:Nelson-Gon/pyfdc.git
cd pyfdc
python3 -m pip install .
```
**Sample usage**
There are two ways to use `pydfc`. In script mode, one does the following:
```shell
python -m pyfdc --method "info" --phrase "cheese" | head
#/pyfdc/pyfdc/pyfdc.py:109: UserWarning: No target_fields were provided, returning fdc_id, ingredients, and description.
# warn("No target_fields were provided, returning fdc_id, ingredients, and description.")
# fdc_id ... description
#0 816524 ... CHEESE
#1 1463368 ... CHEESE
#2 1597534 ... CHEESE
#3 1653804 ... CHEESE
#4 1660793 ... CHEESE
#5 1497465 ... CHEESE
#6 1465399 ... CHEESE
#7 515803 ... CHEESE
#8 500370 ... CHEESE
#
```
The above uses the `get_food_info` method. To use, the `get_food_details` method, one simply sets method to "details"
and provides the target FoodDataCentral ID.
```shell
python -m pyfdc --method "details" --phrase 816524 --fields "nutrients"
# id number name rank unitName
#0 1004 204 Total lipid (fat) 800 g
#1 1257 605 Fatty acids, total trans 15400 g
#2 1079 291 Fiber, total dietary 1200 g
#3 1003 203 Protein 600 g
#4 1005 205 Carbohydrate, by difference 1110 g
#5 1110 324 Vitamin D (D2 + D3), International Units 8650 IU
#6 1008 208 Energy 300 kcal
#7 2000 269 Sugars, total including NLEA 1510 g
#8 1089 303 Iron, Fe 5400 mg
#9 1087 301 Calcium, Ca 5300 mg
#10 1258 606 Fatty acids, total saturated 9700 g
#11 1093 307 Sodium, Na 5800 mg
#12 1253 601 Cholesterol 15700 mg
```
```python
from pyfdc.pyfdc import FoodDataCentral
from pyfdc.utils import set_api_key
```
**Set session api key**
To avoid providing an api key for each call, one can set a session api key as follows:
```python
set_api_key("my_api_key_here")
```
**Key Features**
There is one major class `FoodDataCentral`.
See the [changelog](https://github.com/Nelson-Gon/pyfdc/blob/master/changelog.md)
for more details.:
To instantiate an object:
```python
my_search = FoodDataCentral()
```
To get details about foods for a given search term, one can do the following:
```python
my_search.get_food_info(search_phrase="cheese").head(6)
```
The above will result in the following output:
```shell
#
#UserWarning: No target_fields were provided, returning fdc_id, ingredients, and description.
# fdc_id ingredients description
#0 816524 BELLAVITANO CHEESE (PASTEURIZED MILK, CHEESE C... CHEESE
#1 1210322 BELLAVITANO CHEESE (PASTEURIZED MILK, CHEESE C... CHEESE
#2 1291586 CHEDDAR CHEESE (PASTEURIZED MILK, CHEESE CULTU... CHEESE
#3 1305389 PASTEURIZED COWS' MILK, SALT, CULTURES, ENZYMES. CHEESE
#4 1361608 CULTURED PASTEURIZED MILK, SALT, NON-ANIMAL EN... CHEESE
#5 1420013 FRESH PART-SKIM COW'S MILK, CHEESE CULTURE SAL... CHEESE
```
In the above, we got a warning message because we used defaults out-of-the-box. To customize, we can set
the `target_fields` we wish to have.
```shell
my_search.get_food_info(search_phrase="cheese", target_fields=["description"]).head(4)
# description
# 0 CHEESE
# 1 CHEESE
# 2 CHEESE
# 3 CHEESE
```
To get full details about a given `fdcId`, one can do the following:
```shell
my_search.get_food_details(168977)
```
This will give us the following output(truncated):
```shell
# UserWarning: No target_field was provided, returning low level results.
# 0 1
#0 fdcId 168977
#1 description Agutuk, meat-caribou (Alaskan ice cream) (Alas...
#2 publicationDate 4/1/2019
#3 foodNutrients [{'nutrient': {'id': 2045, 'number': '951', 'n...
#4 dataType SR Legacy
```
The above is a low-level result that may be useful for development purpises.
To get nutrient details:
```shell
my_search.get_food_details(fdc_id= 496446,target_field="nutrients")
# nutrient.id nutrient.unitName nutrient.name \
#0 1089 mg Iron, Fe
#1 1258 g Fatty acids, total saturated
#2 1253 mg Cholesterol
#3 1162 mg Vitamin C, total ascorbic acid
#4 1087 mg Calcium, Ca
#5 1104 IU Vitamin A, IU
# foodNutrientDerivation.description id amount \
#0 Calculated from a daily value percentage per s... 3992103 3.39
#1 Calculated from a daily value percentage per s... 3992107 0.47
#2 Calculated from a daily value percentage per s... 3992106 0.00
#3 Calculated from a daily value percentage per s... 3992105 0.00
#4 Calculated from a daily value percentage per s... 3992102 118.00
#5 Calculated from a daily value percentage per s... 3992104 0.00
# nutrient.number nutrient.rank
#0 303 5400
#1 606 9700
#2 601 15700
#3 401 6300
```
One can also get label nutrients (if they exist):
```shell
my_search.get_food_details(504905, target_field="label_nutrients")
# fat saturatedFat transFat cholesterol sodium ... calcium iron potassium addedSugar calories
#0 15.0 4.5 0.0 84.5 1060.0 ... 80.6 1.08 70.2 1.04 179
#[1 rows x 14 columns]
```
**Credit**
1. **Original Food Data Central API**
The API interfaced is available [here](https://fdc.nal.usda.gov/api-guide.html)
**Thank you very much**.
> To report any issues, suggestions or improvement, please do so
at [issues](https://github.com/Nelson-Gon/pyfdc/issues).
> “Before software can be reusable it first has to be usable.” – Ralph Johnson
---
If you would like to cite this work, please use:
Nelson Gonzabato(2020) pyfdc: A python interface to FoodDataCentral, https://github.com/Nelson-Gon/pyfdc
BibTex:
```shell
@misc{Gonzabato2021,
author = {Gonzabato, N},
title = {pyfdc: A python interface to FoodDataCentral},
year = {2021},
publisher = {GitHub},
journal = {GitHub repository},
howpublished = {\url{https://github.com/Nelson-Gon/pyfdc}},
commit = {20923d9dbea9dcf1b5cba741625b01f6637a6d7b}
}
```