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

Responses

• 200 OK

  application/json

  The request succeeded and a collection of foods returned.

  Example:

  {
    "metadata": {
      "total": 80,
      "limit": 20,
      "offset": 0
    },
    "foods": [
      {
        "revisionId": "66392724-3352-4af9-9579-f9ffb4450411",
        "brand": {
          "id": "7f2591ff-36d6-4344-8596-6e0b25d3e301",
          "name": "McDonald's"
        },
        "name": "French Fries",
        "classification": "Chips & Fries"
      },
      {
        "revisionId": "0789b1fd-fd51-4002-970f-48ee438edec9",
        "brand": {
          "id": "7f2591ff-36d6-4344-8596-6e0b25d3e301",
          "name": "McDonald's"
        },
        "name": "Big Mac Burger",
        "classification": "Sandwiches & Burgers",
      }
    ]
  }

• 400 Bad Request

  application/json

  The request is invalid as outlined in the response message. Further information may exist and if so will be listed in the response details.

  Example:

  {
    "code": 400,
    "message": "Unknown path in 'fields'",
    "details": "Path: 'category'"
  }

• 401 Unauthorized

  application/json

  The request requires user authentication.

  Example:

  {
    "code": 401,
    "message": "Not Authorized"
  }

URI Parameters

• foodId: required (string)

  The id of the food.

Query Parameters

• fields: (string)

  Selector to specify the fields to include in partial responses.

Responses

• 200 OK

  application/json

  The request succeeded and the food returned.

  Example:

  {
    "food": {
      "revisionId": "0d613b29-214a-46d8-b3c6-d94a8f4a5d05",
      "foodId": "46b92291-86cc-4cc5-bce4-40b100c7f90c",
      "brand": {
        "id": "b2c1e370-1e74-421f-b685-513efede17b1",
        "name": "Coca-Cola"
      },
      "tags": [
        {
          "id": "b5dfce01-7215-45d1-bd8a-759bb82dc9bc",
          "name": "Soft Drinks, Soda"
        },
        {
          "id": "becb8a31-799e-4323-931d-63adb43569e8",
          "name": "Sodas, Soft Drinks"
        }
      ],
      "name": "Classic Coca-Cola",
      "classification": "Sodas, Soft Drinks",
      "volume": 240.0,
      "servings": [
        {
          "name": "cup",
          "scale": 1.0,
          "type": "volume"
        },
        {
          "name": "can or bottle",
          "scale": 1.47916666666667,
          "type": "volume"
        },
        {
          "name": "can",
          "scale": 0.925,
          "type": "volume"
        },
        {
          "name": "bottle",
          "scale": 2.4625,
          "type": "volume"
        }
      ],
      "upcs": {
        "0067000008290": {
          "servingIndex": 2,
          "quantity": 1.0
        },
        "0067000004162": {
          "servingIndex": 3,
          "quantity": 1.0
        },
        "0067000004278": {
          "servingIndex": 3,
          "quantity": 1.0
        },
        "0067000001857": {
          "servingIndex": 0,
          "quantity": 1.0
        }
      },
      "nutrients": {
        "energy": 405.0,
        "fat": 0.0,
        "protein": 0.0,
        "sugar": 27.0,
        "fiber": 0.0,
        "sodium": 33.0,
        "cholesterol": 0.0,
        "alcohol": 0.0,
        "potassium": 0.0,
        "caffeine": 23.0
      }
    }
  }

• 400 Bad Request

  application/json

  The request is invalid as outlined in the response message. Further information may exist and if so will be listed in the response details.

  Example:

  {
    "code": 400,
    "message": "Unknown path in 'fields'",
    "details": "Path: 'category'"
  }

• 401 Unauthorized

  application/json

  The request requires user authentication.

  Example:

  {
    "code": 401,
    "message": "Not Authorized"
  }

• 404 Not Found

  application/json

  No food exists for the given id.

  Example:

  {
    "code": 404,
    "message": "Food not found",
    "details": "id: c4e85530-e4b1-421e-b1f8-ae32f39934b9"
  }

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.

Responses

• 200 OK

  application/json

  The request succeeded and a collection of brands returned.

  Example:

  {
    "metadata": {
      "total": 80,
      "limit": 20,
      "offset": 0
    },
    "brands": [
      {
        "id": "fb8d3d1b-1e61-4d32-96ae-dec48ea46e57",
        "region": "us",
        "name": "Apple & Eve"
      },
      {
        "id": "41bc9cd2-78dd-4844-9015-c8c92c19b710",
        "region": "us",
        "name": "Apple Time"
      },
      {
        "id": "c7484dac-78e0-498e-a713-83267a8e82ef",
        "region": "us",
        "name": "Applebee's"
      },
      {
        "id": "aa63f901-8e2d-47e9-a740-114433d7e130",
        "region": "us",
        "name": "Applegate Farms"
      }
    ]
  }

• 400 Bad Request

  application/json

  The request is invalid as outlined in the response message. Further information may exist and if so will be listed in the response details.

  Example:

  {
    "code": 400,
    "message": "Unknown path in 'fields'",
    "details": "Path: 'classification'"
  }

• 401 Unauthorized

  application/json

  The request requires user authentication.

  Example:

  {
    "code": 401,
    "message": "Not Authorized"
  }

URI Parameters

• brandId: required (string)

  The id of the brand.

Query Parameters

• fields: (string)

  Selector to specify the fields to include in partial responses.

Responses

• 200 OK

  application/json

  The request has succeeded and the brand returned.

  Example:

  {
    "brand": {
      "id": "3ebcd32e-7809-460d-8766-467f042beba9",
      "region": "us",
      "name": "Nestle"
    }
  }

• 400 Bad Request

  application/json

  The request is invalid as outlined in the response message. Further information may exist and if so will be listed in the response details.

  Example:

  {
    "code": 400,
    "message": "Unknown path in 'fields'",
    "details": "Path: 'category'"
  }

• 401 Unauthorized

  application/json

  The request requires user authentication.

  Example:

  {
    "code": 401,
    "message": "Not Authorized"
  }

• 404 Not Found

  application/json

  No brand exists for the given id.

  Example:

  {
    "code": 404,
    "message": "Brand not found",
    "details": "id: 43afe4c7-ffd5-4ccd-a14e-c3f297e34d48"
  }

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.

Responses

• 200 OK

  application/json

  The request succeeded and a collection of categories returned.

  Example:

  {
    "metadata": {
      "total": 80,
      "limit": 20,
      "offset": 0
    },
    "categories": [
      {
        "id": "84c81cdc-8ae9-4ee2-9654-9c644e8181f5",
        "region": "us",
        "name": "Alcoholic Drinks",
        "hierarchy": [
          {
            "id": "84c81cdc-8ae9-4ee2-9654-9c644e8181f5",
            "name": "Alcoholic Drinks"
          }
        ],
        "isLeaf": false
      },
      {
        "id": "e9be2377-680f-4f9a-be20-fe7892f05b02",
        "region": "us",
        "name": "Ales & Beers",
        "hierarchy": [
          {
            "id": "84c81cdc-8ae9-4ee2-9654-9c644e8181f5",
            "name": "Alcoholic Drinks"
          },
          {
            "id": "e9be2377-680f-4f9a-be20-fe7892f05b02",
            "name": "Ales & Beers"
          }
        ],
        "parent": "84c81cdc-8ae9-4ee2-9654-9c644e8181f5",
        "isLeaf": true
      },
      {
        "id": "2c4ce015-0180-420c-b937-49a2758be2fd",
        "region": "us",
        "name": "Ciders, Wines",
        "hierarchy": [
          {
            "id": "84c81cdc-8ae9-4ee2-9654-9c644e8181f5",
            "name": "Alcoholic Drinks"
          },
          {
            "id": "2c4ce015-0180-420c-b937-49a2758be2fd",
            "name": "Ciders, Wines"
          }
        ],
        "parent": "84c81cdc-8ae9-4ee2-9654-9c644e8181f5",
        "isLeaf": true
      },
      {
        "id": "2b830a3e-a787-4d67-8a53-de8ba036c350",
        "region": "us",
        "name": "Coolers, Cocktails, Shooters",
        "hierarchy": [
          {
            "id": "84c81cdc-8ae9-4ee2-9654-9c644e8181f5",
            "name": "Alcoholic Drinks"
          },
          {
            "id": "2b830a3e-a787-4d67-8a53-de8ba036c350",
            "name": "Coolers, Cocktails, Shooters"
          }
        ],
        "parent": "84c81cdc-8ae9-4ee2-9654-9c644e8181f5",
        "isLeaf": true
      },
      {
        "id": "5d551ac4-aa63-40af-9be7-21c5399be417",
        "region": "us",
        "name": "Liqueurs, Liquors & Spirits",
        "hierarchy": [
          {
            "id": "84c81cdc-8ae9-4ee2-9654-9c644e8181f5",
            "name": "Alcoholic Drinks"
          },
          {
            "id": "5d551ac4-aa63-40af-9be7-21c5399be417",
            "name": "Liqueurs, Liquors & Spirits"
          }
        ],
        "parent": "84c81cdc-8ae9-4ee2-9654-9c644e8181f5",
        "isLeaf": true
      }
    ]
  }

• 400 Bad Request

  application/json

  The request is invalid as outlined in the response message. Further information may exist and if so will be listed in the response details.

  Example:

  {
    "code": 400,
    "message": "Unknown path in 'fields'",
    "details": "Path: 'classification'"
  }

• 401 Unauthorized

  application/json

  The request requires user authentication.

  Example:

  {
    "code": 401,
    "message": "Not Authorized"
  }

URI Parameters

• categoryId: required (string)

  The id of the category.

Query Parameters

• fields: (string)

  Selector to specify the fields to include in partial responses.

Responses

• 200 OK

  application/json

  The request has succeeded and the category returned.

  Example:

  {
    "category": {
      "id": "3ebcd32e-7809-460d-8766-467f042beba9",
      "region": "us",
      "name": "Nestle"
    }
  }

• 400 Bad Request

  application/json

  The request is invalid as outlined in the response message. Further information may exist and if so will be listed in the response details.

  Example:

  {
    "code": 400,
    "message": "Unknown path in 'fields'",
    "details": "Path: 'category'"
  }

• 401 Unauthorized

  application/json

  The request requires user authentication.

  Example:

  {
    "code": 401,
    "message": "Not Authorized"
  }

• 404 Not Found

  application/json

  No category exists for the given id.

  Example:

  {
    "code": 404,
    "message": "Category not found",
    "details": "id: 4ebad32e-7809-460d-8436-267f012beba9"
  }

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 Category	Leaf Category	Food	Tags
  Top1	Leaf1	Food1	A
  		Food2	B
  	Leaf2	Food3	B
  		Food4	C
  Top2	Leaf3	Food 5	A, B
  		Food6	C, D
  	Leaf4	Food7	B, C
  		Food8	D

  Below are the results from some of the category filters:

  Categories Filter (where 'CategoryX' represents the id of that category)	Resulting Tags
  Top1	A, B, C
  Leaf1	A, B
  Top1,Leaf4	A, B, C, D
  !Leaf1	A, B, C, D
  !Leaf1,Leaf3	B, C, D
  !Top2,Leaf2	A, 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:

  Brand	Food	Tags
  Brand1	Food1	A
  	Food2	B
  	Food3	C
  Brand2	Food4	A, B
  	Food5	A
  	Food6	B
  Brand3	Food7	B, C

  Below are the results from some brands filters:

  Brands Filter (where 'BrandX' represents the id of that brand)	Resulting Tags
  Brand1	A, B, C
  Brand2	A, B
  Brand3	B, C
  Brand2,Brand3	A, B, C
  !Brand1	A, B, C
  !Brand1,Brand2	B, C
  !Brand1,Brand3	A, 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.

Responses

• 200 OK

  application/json

  The request succeeded and a collection of tags returned.

  Example:

  {
    "metadata": {
      "total": 80,
      "limit": 20,
      "offset": 0
    },
    "tags": [
      {
        "id": "7c132457-2979-48be-90d9-0013884b24cc",
        "name": "Fruit Drinks"
      },
      {
        "id": "71c27b1e-f564-4091-b9c8-ac8f76d25f66",
        "name": "Fruit Juices"
      },
      {
        "id": "cac762fb-a70e-471e-96eb-65dde30e331b",
        "name": "Fruit Smoothies"
      }
    ]
  }

• 400 Bad Request

  application/json

  The request is invalid as outlined in the response message. Further information may exist and if so will be listed in the response details.

  Example:

  {
    "code": 400,
    "message": "Unknown path in 'fields'",
    "details": "Path: 'region'"
  }

• 401 Unauthorized

  application/json

  The request requires user authentication.

  Example:

  {
    "code": 401,
    "message": "Not Authorized"
  }

URI Parameters

• tagId: required (string)

  The id of the tag.

Query Parameters

• fields: (string)

  Selector to specify the fields to include in partial responses.

Responses

• 200 OK

  application/json

  The request succeeded and the tag returned.

  Example:

  {
    "tag": {
      "id": "796f4200-5527-460c-82c4-ebaeddf57bc9",
      "name": "Bars, Breakfast Cereals"
    }
  }

• 400 Bad Request

  application/json

  The request is invalid as outlined in the response message. Further information may exist and if so will be listed in the response details.

  Example:

  {
    "code": 400,
    "message": "Unknown path in 'fields'",
    "details": "Path: 'region'"
  }

• 401 Unauthorized

  application/json

  The request requires user authentication.

  Example:

  {
    "code": 401,
    "message": "Not Authorized"
  }

• 404 Not Found

  application/json

  No tag exists for the given id.

  Example:

  {
    "code": 404,
    "message": "Tag not found",
    "details": "id: a2da1442-3abc-4606-a442-aba5534db508"
  }