Food API Documentation

https://foodapi.calorieking.com/v1
Backward Compatibility

The API version will be incremented whenever backward compatibility can not be maintained. Additional fields may be added to a resource response without a change in the API version. Clients should ignore any fields that they do not expect.

Authentication

The API supports authentication via HTTP Basic Auth. Provide your access token as the basic auth username and leave the password blank.

Please keep your access token secret, it is used to track your account's quotas.

If you don't have an access token or your token has been compromised then please contact us.

IP Address Locks

Access to the API from your account can be restricted to certain IP addresses.

Please contact us if you would like to enable this feature.

Caching

The API supports caching through the use of the Last-Modified response header and the corresponding If-Modified-Since request header.

Units

Mass and volume measurements are reported in grams and milliliters. For information on the nutrient units, see Nutrients.

Nutrients

The API supports the following nutrients:

NutrientUnitsKey
EnergykJenergy
Fatgfat
Saturated FatgsatFat
Trans FatgtransFat
Cholesterolmgcholesterol
Sodiummgsodium
Total CarbohydrategtotalCarbs
Fibergfiber
Sugargsugar
Proteingprotein
Vitamin AIUvitaminA
Vitamin CmgvitaminC
Calciummgcalcium
Ironmgiron
Poly Unsaturated FatgpolyUnsatFat
Mono Unsaturated FatgmonoUnsatFat
Omega3 Fatmgomega3Fat
Net CarbohydrategnetCarbs
Sugar AlcoholgsugarAlcohol
Alcoholgalcohol
Potassiummgpotassium
Caffeinemgcaffeine
Partial Responses

Partial responses allow you to improve performance by telling the server exactly what information you're interested in and want returned. To request a partial response, use the fields parameter to specify the fields you want returned. You can use this parameter with any request that returns a response body.

Fields Parameter Syntax

The fields syntax is a comma separated list of field selectors, which can be:

  • The name of a field
  • A nested field by using a/b where b is a field nested in a:
    • To select multiple nested fields you can use a(b,c,d) where b, c, and d are all fields nested in a
    • You can also use a/b and a(b) where a is a collection and b is a field nested in each item
  • A fieldset alias
Fieldset Aliases

Additionally, the /foods resource supports fieldset aliases. Fieldset aliases are denoted by a leading "$" and are a shorthand way of specifying a set of predefined fields.

Fieldset aliases are supplied the same way you would a standard field and can be used together with other supported field selectors to further customize the result. Supported fieldset aliases and the fields they expand out to are:

$summary
Fields
revisionId
brand
name
classification
$detailed
Fields
revisionId
foodId
brand
tags
name
otherNames
description
classification
note
mass
volume
servings
upcs
nutrients
Examples

To return mass along with the summary fieldset when searching for foods:

GET /foods?query=burger&region=us&fields=$summary,mass

{
  "metadata": {
    "total": 5080,
    "limit": 20,
    "offset": 0
  },
  "foods": [
    {
      "revisionId": "4093fb31-bd3a-4100-9c9c-14106ba582fa",
      "brand": {
        "id": "c4697cb5-74b3-437a-a1cd-d663cabd4f9f",
        "name": "McDonald's"
      },
      "name": "Big Mac Burger",
      "classification": "Sandwiches & Burgers",
      "mass": 215.0
    },
    ...
  ]
}

To return tag names along with the summary fieldset when fetching a food.

GET /foods/37216b92-fbea-4acd-9b43-e79721d6c559?fields=$summary,tags/name

{
  "food": {
    "revisionId": "4093fb31-bd3a-4100-9c9c-14106ba582fa",
    "brand": {
      "id": "c4697cb5-74b3-437a-a1cd-d663cabd4f9f",
      "name": "McDonald's"
    },
    "tags": [
      {
        "name": "Fast-Food Chains & Restaurants"
      },
      {
        "name": "Sandwich & Burger"
      },
    ],
    "name": "Big Mac Burger",
    "classification": "Sandwiches & Burgers"
  }
}
Partial Response Examples

To return only the name and id of the foods when doing a search:

GET /foods?region=us&query=orange%20juice&fields=foodId,name

{
  "metadata": {
    "total": 80,
    "limit": 20,
    "offset": 0
  },
  "foods": [
    {
      "foodId": "10f4ab2d-63c4-4dda-a016-400063698f97",
      "name": "Orange Juice, fresh"
    },
    ...
  ]
}

To return the food name and id, and the brand name:

GET /foods?region=us&query=orange%20juice&fields=foodId,name,brand/name

{
  "metadata": {
    "total": 80,
    "limit": 20,
    "offset": 0
  },
  "foods": [
    {
      "foodId": "10f4ab2d-63c4-4dda-a016-400063698f97",
      "brand": {
        "name": "- Average All Brands -"
      },
      "name": "Orange Juice, fresh"
    },
    ...
  ]
}

To return the food name and id, and the brand name and id:

GET /foods?region=us&query=orange%20juice&fields=foodId,name,brand(name,id)

{
  "metadata": {
    "total": 80,
    "limit": 20,
    "offset": 0
  },
  "foods": [
    {
      "foodId": "10f4ab2d-63c4-4dda-a016-400063698f97",
      "brand": {
        "id": "72e34d90-9563-4433-8ec4-c51801d06330",
        "name": "- Average All Brands -"
      },
      "name": "Orange Juice, fresh"
    },
    ...
  ]
}

Selectors can also be used on collections, so you can return all the serving names for a food with:

GET /foods/10f4ab2d-63c4-4dda-a016-400063698f97?fields=servings/name

Or

GET /foods/10f4ab2d-63c4-4dda-a016-400063698f97?fields=servings(name)

{
  "food": {
    "servings": [
      {
        "name": "cup"
      },
      {
        "name": "fruit yields"
      }
    ]
  }
}
Paging

Paging is supported for all requests that return a collection using the limit and offset parameters. These work the same way as in SQL where offset is the zero-based index of the first result to return and limit is the number of results to include in a page. The supported limit values are 1, 5, 10, 20, 30, 50 and 100.

All pageable queries return metadata containing the limit and offset of the query, and also the total number of matching results.

Food Ordering & Grouping

The /foods collection supports advanced ordering and grouping to allow complex interfaces that would otherwise difficult or inefficient to implement.

For example, you could produce an interface that displays the top 2 matching foods from each brand and orders the brands by the relevance of the foods they contain. You could then display a "Show More" link if the brand contained more matches.

GET /foods?region=us&query=orange%20juice&grouping=brand&grouping-limit=3

Average All Brands
  Orange Juice, fresh
  Orange Juice, frozen, concentrate, unsweetened, undiluted
  <Show More>

Tropicana
  Pure Premium, No Pulp Orange Juice
  Pure Premium, Calcium & Vitamin D Orange Juice
  <Show More>

Simply Orange
  Original Pulp Free Orange Juice
  Simply Lemonade Juice
  <Show More>

Minute Maid
  100% Premium Original Orange Juice
  Light Pure Squeezed Low Pulp Orange Juice, with Calorie & Vitamin D
  <Show More>

Florida's Natural
  100% Original Orange Juice
  100% Orange Juice with Calcium & Vitamin D
  <Show More>

Jamba Juice
  Fruit & Veggie, Orange Carrot Karma Smoothie
  Purely Orange Freshly Squeezed Juice
  <Show More>

Arby's
  Orange Juice

Olive Garden
  Kids' Orange Juice
  Orange Juice

Food ordering & grouping is controlled by the 4 parameters: grouping, grouping-limit, grouping-order, and order.

Processing Grouped Food Results

The API response does not include any containers for the groups. Track changes in the foods' grouping field when parsing the response to obtain this information.

Foods

A food represents a product in all its packaging or consumption sizes - as long as they have equivalent nutritional information. Every food belongs to one brand and one category, and has one or more servings.

FieldTypeDescription
foodIduuidA UUID identifying the food. This does not change when the food changes.
revisionIduuidA UUID identifying the revision of the food. This will change whenever the food changes. If the revisionId of a food has not changed, you are guaranteed that the foods nutrients and servings have not changed either.
regionstringThe region associated with the food.
brandbrandThe food's brand.
categorycategoryThe food's category.
tags[]list<tag>A list of tags associated with the food.
namestringThe name of the food.
classificationstringThe food's classification.
massstringThe mass (in grams) associated with the nutrient information if it is known.
volumestringThe volume (in milliliters) associated with the nutrient information if it is known.
servings[]listA list of one or more servings for the food.
servings[].namestringThe name of the serving.
servings[].scalefloatThe scale of the serving compared to the inforamiotn attached to the food (eg. mass, volume, nutrients).
servings[].typestringOne of 'mass', 'volume', or 'serving' indicating the type of the serving. A type of 'serving' is used when the mass or volume is unknown.
nutrientsobjectA key:value listing of available nutrient information. See nutrients for a list of available nutrients.
Resource URIs

Returns a collection of all the foods in the CalorieKing database.

Query Parameters

  • query: (string)

    Filter based on this query string. The exact meaning of this string depends on the query-type parameter.

  • query-type: one of (fts, prefix)

    Dictates how the query parameter is interpreted:

    • fts - Search for resources matching the query string using full text search (case insensitive).
    • prefix - Search for resources with names beginning with the query string (case insensitive).
  • region: one of (au, us)

    Filter results by region.

  • fields: (string)

    Selector to specify the fields to include in partial responses.

  • limit: (number)

    The number of results to include in requests when paging.

  • offset: (number)

    The index (zero-based) of the first result to return when paging.

  • brands: (string)

    Filter the results by brands. The syntax for the parameter is a comma separated list of brand IDs where you can:

    • Limit the results to a brand by specifying a brand ID
    • Exclude a brand from the results by prefixing the brand ID with a exclamation mark
    • Specify multiple brands to include or exclude by using a comma separated list

    For example, to return results for only McDonald's and McDonald's McCafe:

    GET /foods?region=us&brand=c4697cb5-74b3-437a-a1cd-d663cabd4f9f,754cd4a3-a253-4c80-8807-8b039d14c212

    To exclude Average All Brand results:

    GET /foods?region=us&query=orange&brand=!72e34d90-9563-4433-8ec4-c51801d06330
  • tags: (string)

    Filter results by tags. The syntax of this parameter should be a comma separated list of tag IDs. To exclude a certain tag, prefix the tag ID with an exclamation mark.

    For example, to limit a search to fruits:

    GET /foods?region=us&query=apple&tags=e6c09930-91af-4ef2-8e07-5d70fccb57a2

    To limit a search to fruits but exclude dried fruits:

    GET /foods?region=us&query=apple&tags=e6c09930-91af-4ef2-8e07-5d70fccb57a2,!42e5298c-293f-4ca4-9a89-d7708cb3907b
  • categories: (string)

    Filter results by categories. This is a comma separated list of category ids. The list may be prepended with a '!' to invert the filter and return foods that are not in any of the specified categories. Non-leaf categories may be included in this filter. In this case, the filter will return foods contained in any of the leaf categories under the non-leaf category.

  • classifications: (string)

    Filter results by classifications. This is a comma separated list of classification strings. Classification strings can be enclosed in double quotes to escape commas if necessary. The list may be prepended with a '!' to return foods without the listed classifications.

  • grouping: one of (brand, classification)

    Groups results either by brand or classification. See Food Ordering & Grouping for more details.

  • grouping-order: (string)

    Specifies the order of groups in the format field:direction, when a grouping has been specified. See Food Ordering & Grouping for more details.

    • field (required): one of (rank, name)
      • rank: Order the groups according to the relevance of the foods it contains.
      • name: Order the groups according to the name of the group.
    • direction: one of (asc, desc)
      • asc (default): Order the groups ascending.
      • desc: Order the groups descending.

    Note: A direction of ascending when used together with rank will result in the most relevant results appearing first.

  • grouping-limit: (number)

    Limit the number of foods included within a group. See Food Ordering & Grouping for more details.

  • order: (string)

    The order in which the foods will be returned, specified in the format field:direction.

    • field (required): one of (rank, name)
    • direction: one of (asc, desc). Defaults to 'asc' if omitted. A direction of ascending when used together with rank will result in the most relevant results appearing first.

    e.g. To order foods by name descending, order=name:desc

Returns a specific food from the CalorieKing database.

URI Parameters

  • foodId: required (string)

    The id of the food.

Query Parameters

Brands

A brand or restaurant from the CalorieKing database. Every food belongs to a single brand.

FieldTypeDescription
iduuidA UUID identifying the brand
namestringThe name of the brand
regionstringThe region associated with the brand

Each region contains a special brand called Average All Brands that contains generic foods (eg. apple, banana, etc). These brands can be identified using their UUID:

RegionUUID
au4a497106-5e8c-4729-9451-667c2b57514b
us72e34d90-9563-4433-8ec4-c51801d06330
Resource URIs

Returns a collection of brands from the CalorieKing database.

Query Parameters

  • classifications: (string)

    Filter brands to those with foods with the specified classifications. This is a comma separated list of classification strings. Classification strings can be enclosed in double quotes to escape commas if necessary. The list may be prepended with a '!' to return brands with foods without the listed classifications.

  • categories: (string)

    Filter brands to those with foods in the specified categories. This is a comma separated list of category ids. The list may be prepended with a '!' to invert the filter and return brands with foods that are not in any of the specified categories. Non-leaf categories may be included in this filter. In this case, the filter will work on foods contained in any of the leaf categories under the non-leaf category.

  • tags: (string)

    Filter brands to those with foods with the specified tags. This is a comma separated list of tag ids. Each tag id can be prefixed with a '!' to indicate that foods with that tag should be excluded, rather than included.

    For Example, to select US brands that contain foods tagged as 'Fruit', but not as 'Dried Fruit'

    GET /brands?region=us&tags=2dff5ec3-2e9f-4da9-852e-61efbf2d67b8,!c3f2271b-add6-4d9c-937e-317c610eb13a

  • order: one of (asc, desc)

    Results are ordered alphabetically by name. This field indicated whether they are in ascending or descending alphabetical order.

  • query: (string)

    Filter based on this query string. The exact meaning of this string depends on the query-type parameter.

  • query-type: one of (fts, prefix)

    Dictates how the query parameter is interpreted:

    • fts - Search for resources matching the query string using full text search (case insensitive).
    • prefix - Search for resources with names beginning with the query string (case insensitive).
  • region: one of (au, us)

    Filter results by region.

  • fields: (string)

    Selector to specify the fields to include in partial responses.

  • limit: (number)

    The number of results to include in requests when paging.

  • offset: (number)

    The index (zero-based) of the first result to return when paging.

Returns a specific brand from the CalorieKing database.

URI Parameters

  • brandId: required (string)

    The id of the brand.

Query Parameters

Categories

Categories organize foods into an hierarchical tree structure. Each food is directly associated with one, and only one category. Categories can either contain other categories, or contain foods, but not both. Categories that contains foods are refered to as leaf categories.

FieldTypeDescription
iduuidA UUID identifying the category
regionstringThe region associated with the category
namestringThe name of the category
parentuuidThe id of the category that contains this category. This field will not be present for top level categories.
hierarchy[]listAn array of all categories from the top level category down to this category, showing the position of this category in the hierarchy tree. This field enables a fully qualified category name to be displayed, with links to parent categories, without needing to fetch parent categories. Each entry in this array is a HierarchyEntry as described below.
hierarchy[].iduuidThe id of the category
hierarchy[].namestringThe name of the category
isLeafbooleanIndicates whether the category is a leaf. Leaf categories contain foods, but no other categories. Non-leaf categories contain other categories, but not foods.
Resource URIs

Returns a list of categories matching the specified criteria.

Query Parameters

  • classifications: (string)

    Filter categories to those with foods with the specified classifications. This is a comma separated list of classification strings. Classification strings can be enclosed in double quotes to escape commas if necessary. The list may be prepended with a '!' to return categories with foods without the listed classifications.

  • brands: (string)

    Filter categories to those with foods in the specified brands. This is a comma separated list of brand ids. The list may be prepended with a '!' to invert the filter and return categories with foods that are not in any of the specified brands.

  • tags: (string)

    Filter categories to those with foods with the specified tags. This is a comma separated list of tag ids. Each tag id can be prefixed with a '!' to indicate that foods with that tag should be excluded, rather than included.

    For Example, to select US categories that contain foods tagged as 'Fruit', but not as 'Dried Fruit'

    GET /categories?region=us&tags=2dff5ec3-2e9f-4da9-852e-61efbf2d67b8,!c3f2271b-add6-4d9c-937e-317c610eb13a

  • order: one of (asc, desc)

    Results are ordered alphabetically by name. This field indicated whether they are in ascending or descending alphabetical order.

  • query: (string)

    Filter based on this query string. The exact meaning of this string depends on the query-type parameter.

  • query-type: one of (fts, prefix)

    Dictates how the query parameter is interpreted:

    • fts - Search for resources matching the query string using full text search (case insensitive).
    • prefix - Search for resources with names beginning with the query string (case insensitive).
  • region: one of (au, us)

    Filter results by region.

  • fields: (string)

    Selector to specify the fields to include in partial responses.

  • limit: (number)

    The number of results to include in requests when paging.

  • offset: (number)

    The index (zero-based) of the first result to return when paging.

  • parents: (string)

    Filter returned categories based on their parent. This is a comma separated list of category ids (uuid). This parameter may be inverted by prepending a '!'.

  • is-leaf: (boolean)

    Filter returned categories based on whether or not they are a leaf categories. Leaf categories contain foods. Non-leaf categories contain other categories.

Returns a specific category from the CalorieKing database.

URI Parameters

  • categoryId: required (string)

    The id of the category.

Query Parameters

Tags

Tags are pieces of information associated with foods to convey further information about them. For example, an apple and a banana may both be tagged as 'Fresh' and 'Fruit', whilst tinned peaches may be tagged as 'Canned' and 'Fruit'. Each food can have zero or more associated tags, and a tag can be associated with many foods.

FieldTypeDescription
iduuidA UUID identifying the tag
namestringThe name of the tag
Resource URIs

Returns a collection of all the tags in the CalorieKing database.

Query Parameters

  • classifications: (string)

    Filter tags to those with foods with the specified classifications. This is a comma separated list of classification strings. Classification strings can be enclosed in double quotes to escape commas if necessary. The list may be prepended with a '!' to return tags with foods without the listed classifications.

  • categories: (string)

    Filter tags to those associated with foods in the specified categories. This is a comma separated list of category ids. The list may be prepended with a '!' to invert the filter and return tags associated with foods that are not in any of the specified categories. Non-leaf categories may be included in this filter. In this case, the filter will work on foods contained in any of the leaf categories under the non-leaf category.

    Examples

    Given the following categories, containing foods with the associated tags:

    Top Level CategoryLeaf CategoryFoodTags
    Top1Leaf1Food1A
    Food2B
    Leaf2Food3B
    Food4C
    Top2Leaf3Food 5A, B
    Food6C, D
    Leaf4Food7B, C
    Food8D

    Below are the results from some of the category filters:

    Categories Filter (where 'CategoryX' represents the id of that category)Resulting Tags
    Top1A, B, C
    Leaf1A, B
    Top1,Leaf4A, B, C, D
    !Leaf1A, B, C, D
    !Leaf1,Leaf3B, C, D
    !Top2,Leaf2A, B
  • brands: (string)

    Filter tags to those associated with foods in the specified brands. This is a comma separated list of brand ids. The list may be prepended with a '!' to invert the filter and return tags associated with foods that are not in any of the specified brands.

    Examples

    Given the following brands, containing foods with the associated tags:

    BrandFoodTags
    Brand1Food1A
    Food2B
    Food3C
    Brand2Food4A, B
    Food5A
    Food6B
    Brand3Food7B, C

    Below are the results from some brands filters:

    Brands Filter (where 'BrandX' represents the id of that brand)Resulting Tags
    Brand1A, B, C
    Brand2A, B
    Brand3B, C
    Brand2,Brand3A, B, C
    !Brand1A, B, C
    !Brand1,Brand2B, C
    !Brand1,Brand3A, B
  • order: one of (asc, desc)

    Results are ordered alphabetically by name. This field indicated whether they are in ascending or descending alphabetical order.

  • query: (string)

    Filter based on this query string. The exact meaning of this string depends on the query-type parameter.

  • query-type: one of (fts, prefix)

    Dictates how the query parameter is interpreted:

    • fts - Search for resources matching the query string using full text search (case insensitive).
    • prefix - Search for resources with names beginning with the query string (case insensitive).
  • fields: (string)

    Selector to specify the fields to include in partial responses.

  • limit: (number)

    The number of results to include in requests when paging.

  • offset: (number)

    The index (zero-based) of the first result to return when paging.

Returns a specific tag from the CalorieKing database.

URI Parameters

  • tagId: required (string)

    The id of the tag.

Query Parameters