NOTE: THIS PACKAGE IS UNRELATED TO THE OFFICIAL USDA FOOD DATA API
usda-food-data-api-server
NOTE: THIS PACKAGE IS UNRELATED TO THE OFFICIAL USDA FOOD DATA API
Data links referenced/used by this program provided by:
U.S. Department of Agriculture, Agricultural Research Service. FoodData Central, 2019. fdc.nal.usda.gov.
A REST and GraphQL server to serve the USDA Food Data API. The REST version tries to be compatible with the official USDA Food Data APIs, but cannot guarantee interoperability.
Getting the USDA Food Data into a MongoDB
To run this API server, you first need the USDA Food Data imported into a
MongoDB database using the usda-food-data-api-builder
package. A MongoDB dump
that doesn't come with the performance requirements.
Restoring from the MongoDB dump
If your goal is to quickly setup this project, you can download a gzip MongoDB
dump from the releases on the
usda-food-data-api-builder
repo:
# curl -L https://github.com/dudeami/usda-food-data-api-builder/releases/download/v1.0.2/usda-food-data-linked-v1.0.2.gz -O
# mongorestore --uri mongodb://localhost/usda-food-data --db usda-food-data --gzip --archive=./usda-food-data-linked-v1.0.2.gz
The mongorestore
process took ~5 minutes on the Windows x64 machine used to
develop this.
Make sure to replace mongodb://localhost/usda-food-data
with your MongoDB URI.
Once the database is setup, you can continue down to "Running the server"
Building
Alternatively, you can use the
usda-food-data-api-builder
to build this data.
Running the server
Now that the data is in place, you can run the server. The fastest way to do this is to call the package via npx.
npx usda-food-data-api-server --port 4000
It will ask for a MongoDB URI to connect to, and save this to
usda-food-data.json
for future runs. The API server will then be live on port
4000
.
Missing functionality and differences
While this project aims to replicate the USDA Food Data API, it hasn't be tested for accuracy against it. The API request are the same, but slight differences might occur. A list of known issues are:
- Usage of the
format
query option. All queries, including the search, will return full size documents with thenutrients
filter applied. A version withAbridgedFoodItem
is planned. - No authentication, the API is wide open with no rate limits. Make sure to place this behind your own authentication system. An example repo of an auth-based API using this package is planned.
REST API
The rest API parameters match the USDA api. These can be viewed at:
https://fdc.nal.usda.gov/api-spec/fdc_api.html https://app.swaggerhub.com/apis/fdcnal/food-data_central_api/1.0.0
GraphQL
The GraphQL queries supported closely mirror the REST API. You can look at
./schema.graphql
, at the bottom is the Query
schema. For easy reference, it
will also be listed here:
union FoodItem =
FoundationFoodItem
| BrandedFoodItem
| SurveyFoodItem
| SRLegacyFoodItem
| AbridgedFoodItem
type Query {
food(fdcId: Int!): FoodItem
foods(fdcIds: [Int]!): [FoodItem]
foodList(
nutrients: [Int]
dataType: [String]
pageSize: Int
pageNumber: Int
sortBy: String
sortOrder: String
brandOwner: String
): [FoodItem]
foodSearch(
query: String!
nutrients: [Int]
dataType: [String]
pageSize: Int
pageNumber: Int
sortBy: String
sortOrder: String
brandOwner: String
): [FoodItem]
}
Make note of the FoodItem
union. To better replicate the results possible with
the USDA REST api, these data types did not get seperate queries. Your graphql
query will need to handle each data type you expect, else unused data types
should be filtered out using the dataType
query parameter. An example query using foodSearch
for Foundation
items:
query {
foodSearch(query: "BEANS", dataType: ["Foundation"]) {
... on FoundationFoodItem {
scientificName
description
}
}
}
Here is a table of the dataType
's able to be requested, and their
corresponding schemas:
dataType | Schema |
---|---|
"Foundation" |
FoundationFoodItem |
"Branded" |
BrandedFoodItem |
"Survey" |
SurveyFoodItem |
"SR Legacy" |
SRLegacyFoodItem |
Thanks
Thank you to the USDA and all the authors involved in the dependencies of this project. Without that work this tool would not exist.