United States Department of Agriculture
Agricultural Research Service

USDA Food Composition Databases


Back to API Overview Other API docs: Food Reports Nutrient Reports Search

What are Lists?

You may request a list of foods, nutrients or food groups. List requests are good for providing your users with a paged browse and select experience. For example, your application might allow users to select a food from a foods list to generate a Food Reports request.

How it Works

Basically, you need to indicate the type of list you're requesting and the number of items you want returned on the list up to a maximum of 1500 items in a single request. You can also specify an offset (a zero-based start point) into a list for a paged experience.

Request Parameters

Your api_key is the only required parameter to generate a list. With no other parameters the request will return 50 foods items sorted by food name beginning with the first item (0 offset) in JSON format.

api_keyyn/aMust be a data.gov registered API key
ltnflist type(lt): d = derivation codes, f = food , n = all nutrients, ns = speciality nutrients, nr = standard release nutrients only,g = food group
maxn50 maximum number of items to return
offsetn0 beginning item in the result set
sortnn sort order: n=name or id (Meaning of id varies by list type: nutrient number for a nutrient list, NDBno for a foods list ,food group id for a food group list
format1nJSONreport format: JSON or XML

1Format can also be sent in the request header: Content-Type: application/json or Content-Type:application/xml.

Response Elements

The list response is very simple, consisting of some metadata about your request and a list of names and id's. The meaning of the name and id elements are dependent on the type of list requested in the lt parameter. If you have requested a list of foods, then the name element will refer to the name of the food and the id to the food's NDBno. For food groups lists, name references the name of the food group and id to the food group's unique id. And, for nutrients, name refers to the nutrient name and id to the unique id assigned to each nutrient in the database called nutrient_no.

list information about the request and the items returned
type type of list requested
start beginning offset
end ending offset
total number of items in the list
sort sort order of the list
srStandard Release version of the data being reported
item information about individual items on the list
idndbno for type 'f'; nutrient no for type 'n' or group no for type 'g'
nameitem name

Some Examples

These examples illustrate how to request a list of foods sorted by food name.


Browser: https://api.nal.usda.gov/ndb/list?format=xml&lt=g&sort=n&api_key=DEMO_KEY
CURL: curl -H "Content-Type:application/xml" -d '<list><lt>f</lt><sort>n</sort></list>' DEMO_KEY@api.nal.usda.gov/ndb/list


Browser: https://api.nal.usda.gov/ndb/list?format=json&lt=f&sort=n&api_key=DEMO_KEY
CURL: curl -H "Content-Type:application/json" -d '{"lt":"f","sort":"n"}' DEMO_KEY@api.nal.usda.gov/ndb/list