Build your request:

Username:
Password:
Function:
User ID:
Object:
Filter:
Attribute
Subfunction:
Ingredient ID:
Name:
Data:
Limit:
Quantity
Attributes:
ATTACH INGREDIENT+
Fields:
=
+

ATTACH INGREDIENT:

X

ID

NAME

QUANTITY

COOKING METHOD

ADD
// Get results using JSONP:
function myCallback(result) { //Define a function to be called after we receive the data
    
    if( result.status == 200 ){ //ON SUCCESS:
        console.log(result) //output the result to the console
    
    }else{ // ON ERROR:
        console.log('ERROR '+result.status+': '+result.msg)
    }
}
//Run the request:
var script = document.createElement('script')
script.src = 'https://[USERNAME]:[PASSWORD]@[URL]&callback=myCallback'
document.getElementsByTagName('head')[0].appendChild(script)
require 'rubygems'
require 'json'
require 'rest-client'

# Get json results using RestClient.
response = RestClient.get 'https://[USERNAME]:[PASSWORD]@[URL]', 
	{:accept => :json}
    
if response.code == 200
	# Convert the string to a JSON Object
	data = JSON.parse(response)
	# Print the returned json data out
	puts JSON.pretty_generate(data)

	#Loop through each object and print out their id
	for item in data; 
		puts item["id"]
	end
else
	#We have an error
end
// Get results using JSONP:
var requsetURL = 'https://[USERNAME]:[PASSWORD]@[URL]&callback=?'

$.getJSON( requestURL, function( result ){ //Define a function to be called after we receive the data

	if( result.status == 200 ){ //ON SUCCESS:
        console.log(result) //output the result to the console
    
    }else{ // ON ERROR:
        console.log('ERROR '+result.status+': '+result.msg)
    }
} )
/*Note: Json library needs to be import for the results.*/
/*imports*/
import java.io.BufferedReader;
import java.io.IOException;
import java.io.InputStreamReader;
import java.net.Authenticator;
import java.net.PasswordAuthentication;
import java.net.URL;
import java.net.URLConnection;
import org.json.JSONArray;
import org.json.JSONException;
import org.json.JSONObject;

public class NutriticsApi {
	public static void main(String [] arg) throws IOException, JSONException
		{
		//CREATE AN AUTHENTICATOR:
		Authenticator.setDefault(new Authenticator() {
			String username="[USERNAME]";
			String password="[PASSWORD]";
			@Override
			protected PasswordAuthentication getPasswordAuthentication() {          
				return new PasswordAuthentication(username, password.toCharArray());
			}
		});
		URL url = new URL("[URL]");
		URLConnection conn = url.openConnection();
		BufferedReader in = new BufferedReader(new InputStreamReader(conn.getInputStream()));
		String inputLine, output = "";
		while ((inputLine = in.readLine()) != null) {
			output += inputLine;
		} 
		
		// HOW TO GET THE FIRST RESULT:
		JSONArray newArr= new JSONArray(output);
		System.out.println(newArr.getJSONObject(0)); 
		
		// HOW TO LOOP THROUGH RESULTS TO GET INDIVIDUAL FIELDS:
		for(int i=0; i<newArr.length(); i++) {
			JSONObject dataObj= newArr.getJSONObject(i);
			System.out.println(dataObj.getString("id")); //output the id number for each result
		} 
	}
}
#Example to use an API call with Python v2 and authentication
#You have to use these basic libraries
import urllib2
import sys
import re
import base64
import json
from urlparse import urlparse

theurl = 'https://[URL]'
username = '[USERNAME]'
password = '[PASSWORD]'

req = urllib2.Request(theurl)
try:
    handle = urllib2.urlopen(req)
except IOError, e:
    # Here we want to fail
    pass
else:
    sys.exit(1)

if not hasattr(e, 'code') or e.code != 401:
    # Uknown error (no response code)
    sys.exit(1)

#We extract scheme and realm
authline = e.headers['www-authenticate']
authobj = re.compile(r'''(?:\s*www-authenticate\s*:)?\s*(\w*)\s+realm=['"]([^'"]+)['"]''',re.IGNORECASE)
matchobj = authobj.match(authline)

if not matchobj:
    # here something is wrong (you have to catch an error)
    print authline
    sys.exit(1)

scheme = matchobj.group(1)
realm = matchobj.group(2)
# here we've extracted the scheme and the realm from the header
if scheme.lower() != 'basic':
    # here something is wrong (you have to catch an error)
    sys.exit(1)

base64string = base64.encodestring('%s:%s' % (username, password))[:-1]
authheader =  "Basic %s" % base64string
req.add_header("Authorization", authheader)

try:
    handle = urllib2.urlopen(req)
except IOError, e:
    # authentication failed
    print "The username or password is wrong."
    sys.exit(1)

#We read the result
thepage = handle.read()

#Print the returned json data out
print thepage;

jsondata = json.loads(thepage)
#Loop through each object and print out their id
for item in jsondata:
    print item["id"]
//BASIC EXAMPLE:

$requestURL = "https://[USERNAME]:[PASSWORD]@[URL]";

if($result = file_get_contents( $requestURL ) ) {

	$result = json_decode( $result, true ); //unpack the response into an array
    
	if( $result['status'] == 200 ){ //ON SUCCESS:
		print_r($result); // print the full object
        
	}else{ //ON ERROR:
		die('ERROR '.$result['status'].': '.$result['msg']);
	}
    
}else die("There was an error sending the request");
'How to import REST API data into a Microsoft Excel Workbook:
'Open the excel VBA editor and paste the code below into a new module.
'Next, create a button on sheet1 and choose getNutritics as the onclick function.

Sub getNutritics()
    URL = "https://[URL]"
    user = "[USERNAME]"
    pass = "[PASSWORD]"
    Set httpReq = CreateObject("MSXML2.ServerXMLHTTP.6.0")
    httpReq.Open "GET", URL, False
    httpReq.setRequestHeader "Content-Type", "application/xml"
    httpReq.setRequestHeader "Accept", "application/xml"
    httpReq.setRequestHeader "Authorization", "Basic " + Base64Encode(user + ":" + pass)
    httpReq.send
    'MsgBox httpReq.responseText
    n2XlJSONParser (httpReq.responseText)   'displays the result in sheet 1
End Sub


'JSON parsing function
'http://www.mrexcel.com/forum/excel-questions/640780-parse-json-excel-visual-basic-applications-3.html
'parses a JSON string into a range of cells
Sub n2XlJSONParser(Src)

    Dim ws As Worksheet     ' Target worksheet for extracted data
    Dim TLen As Integer     ' Total length of of input cell data
    Dim columnsCR As Integer ' limit number of data pairs before forced Carriage Return
    Dim cCR As Integer      ' Runtime modified carriage return value for relative reference from start.
    Dim lenLim As Integer   ' Data lenth limit to cause a new row.  0 = none
    Dim rStart As Integer   ' Starting output row
    Dim cStart As Integer   ' Starting output column
    Dim rOut As Integer     ' Dest Row for output
    Dim cOut As Integer     ' Dest Col for output
    Dim nDex As Integer     ' Current position in Source string
    Dim nDex2 As Integer    ' further index to find end quote
    Dim nDexChr As String   ' The character at nDex
    Dim n2This As String    ' value within from nDex -> nDex2 range
    Dim records As Integer  ' Total number of records to report parsed.
    
    ' Propagation rules:
    ' A brace "{" indents the table 1 column.
    ' An end brace "}" un-indents the table (is that a word?).
    ' Quotes are partial delimiters to find a string value to extract by looking ahead to the next quote.
    ' colons and commas are minor delimiters; a comma looks back to the previous colon.
    ' "}," is a major delimiter, and causes the extraction to start a new row.
    
    ' First assign the source
    Set ws = ActiveWorkbook.Worksheets(1)
    'Src = ws.Range("A4").Value  ' Cell that contains JSON data to parse.
    TLen = Len(Src)
    records = 0
    
    ' Initialize cell output behavior.  Adjust these to suit.
    rStart = 1          ' Start output in row 1
    cStart = 1          ' Start output in "A" column
    columnsCR = 0       ' Number of columns, after which, force the start of a new row. _
                        ' _ A ZERO value turns this off. (even numbers work best)
    lenLim = 0          ' If string longer than this, start new row.  A ZERO value turns this off.
                        '...if you use lenLim, variable record lengths can break table structure.
    
    ' Set up assorted variables
    rOut = rStart
    cOut = cStart
    Sheet1.Cells(rStart, cStart).Activate ' This is the starting output cell.
    cStart = cStart - 1 ' Pay no attention to the man behind the curtain!
    
    ' Initialize nDex
    ' The nDex crawls through the Source, leaving nDex2 behind.  When it finds a delimiter, it grabs _
    ' what is in between the two NDex counters.  Then it brings up nDex2 and continues.  This is like _
    ' an inch-worm process through the source data.  It's smart enough to know to look for the next _
    ' quote after finding a quote.  This way it won't have to check EVERY character of data.
    ' A future version will increase speed dramatically by looking ahead for next delimiter.
    nDex = 1
    nDex2 = nDex
    
    ' MAIN LOOP
    Do While nDex <= TLen
        nDexChr = Mid(Src, nDex, 1) ' Get the character sitting at the nDex location
    
        ' Find what's at the nDex location
        If nDexChr = """" Then  ' Is it a quote?
            nDex2 = nDex        ' Bring up the tail
            nDex = InStr(nDex2 + 1, Src, """")  ' Find the next quote
            n2This = Mid(Src, nDex2 + 1, (nDex - nDex2) - 1)    'Get what is in the quotes
            ws.Cells(rOut, cOut) = n2This ' Dump the first found data here and now.
            records = records + 1
            nDex = nDex + 1 ' increment the inchworm
            nDex2 = nDex    ' ...and bring up the tail
            cOut = cOut + 1
                            
        ElseIf nDexChr = "," Then ' Is it a comma?
            If nDex2 <> nDex Then ' Should we look back?
                n2This = Mid(Src, nDex2 + 1, (nDex - nDex2) - 1)    ' Get what's between the head and tail.
                ws.Cells(rOut, cOut) = n2This   ' Dump data into cell
                records = records + 1
                cOut = cOut + 1 ' next output cell in a new column
            End If
            nDex = nDex + 1
            nDex2 = nDex
            ' encountered comma now see if we should start new line.
            If (cOut >= cCR And columnsCR > 0) Or (Len(n2This) > lenLim And lenLim <> 0) Then
                rOut = rOut + 1
                cOut = cStart
                cCR = cStart + columnsCR
            End If
                       
        ElseIf nDexChr = "}" Then
            cStart = cStart - 1
            cCR = cStart + columnsCR
            If nDex <> nDex2 Then   ' didn't start here so look back.
                n2This = Mid(Src, nDex2 + 1, (nDex - nDex2) - 1)
                ws.Cells(rOut, cOut) = n2This
                records = records + 1
            End If
            nDex = nDex + 1
            nDex2 = nDex
           
            If InStr(nDex, Src, ",") = nDex Then    ' is this character a comma?
                rOut = rOut + 1
                cOut = cStart
            Else:
                cOut = cOut + 1
            End If
            nDex = nDex + 1
            
        ElseIf nDexChr = "{" Then
            cStart = cStart + 1
            If cOut < cStart Then
                cOut = cStart
            End If
            cCR = cStart + columnsCR
            nDex = nDex + 1
        
        Else:
            nDex = nDex + 1
        End If
                
        Loop
        MsgBox records & " total records were parsed."
    
End Sub

Function Base64Encode(sText)
    Dim oXML, oNode
    Set oXML = CreateObject("Msxml2.DOMDocument.3.0")
    Set oNode = oXML.createElement("base64")
    oNode.DataType = "bin.base64"
    oNode.nodeTypedValue = Stream_StringToBinary(sText)
    Base64Encode = oNode.Text
    Set oNode = Nothing
    Set oXML = Nothing
End Function


'Stream_StringToBinary Function 2003 Antonin Foller, http://www.motobit.com
'Text - string parameter To convert To binary data
Function Stream_StringToBinary(Text)
  Const adTypeText = 2
  Const adTypeBinary = 1

  'Create Stream object
  Dim BinaryStream 'As New Stream
  Set BinaryStream = CreateObject("ADODB.Stream")

  'Specify stream type - we want To save text/string data.
  BinaryStream.Type = adTypeText

  'Specify charset For the source text (unicode) data.
  BinaryStream.Charset = "us-ascii"

  'Open the stream And write text/string data To the object
  BinaryStream.Open
  BinaryStream.WriteText Text

  'Change stream type To binary
  BinaryStream.Position = 0
  BinaryStream.Type = adTypeBinary

  'Ignore first two bytes - sign of
  BinaryStream.Position = 0

  'Open the stream And get binary data from the object
  Stream_StringToBinary = BinaryStream.Read

  Set BinaryStream = Nothing
End Function

'Stream_BinaryToString Function
'2003 Antonin Foller, http://www.motobit.com
'Binary - VT_UI1 | VT_ARRAY data To convert To a string
Function Stream_BinaryToString(Binary)
  Const adTypeText = 2
  Const adTypeBinary = 1

  'Create Stream object
  Dim BinaryStream 'As New Stream
  Set BinaryStream = CreateObject("ADODB.Stream")

  'Specify stream type - we want To save text/string data.
  BinaryStream.Type = adTypeBinary

  'Open the stream And write text/string data To the object
  BinaryStream.Open
  BinaryStream.Write Binary

  'Change stream type To binary
  BinaryStream.Position = 0
  BinaryStream.Type = adTypeText

  'Specify charset For the source text (unicode) data.
  BinaryStream.Charset = "us-ascii"

  'Open the stream And get binary data from the object
  Stream_BinaryToString = BinaryStream.ReadText
  Set BinaryStream = Nothing
End Function

    DOCUMENTATION

  • Welcome
  • Introduction
  • Nutritics Objects
  • Functions
  • LIST
  • DETAIL
  • CREATE
  • MODIFY
  • DELETE
  • ADMIN
  • HELP
  • Response Codes
  • What's new in v1.1

v1.1betaWelcome

Nutritics API allows you to leverage the power of the world's favourite nutrition engine in your own app, program or website. Integration requires you to either be or to hire a developer. The API can be accessed from any programming language which can connect to the internet.

Most common uses for our API

  • Search our vast international databases
  • Analyse recipes from your own app or platform
  • Analyse a diet from your own app or platform
  • Generate a meal plan from your own app or platform
  • Control Nutritics user data

Introduction

Working with the API is very straight forward. All requests are made via HTTPS URLs. Each URL contains a set of parameters which specify the data you wish to retrieve. The data is always returned in JSON format.

For example, here's a simple request which searches our database for the keyword "bananna" https://[USERNAME]:[PASSWORD]@https://www.nutritics.com/api/v1.1/LIST/food=bananna

API explorer

You can use our powerful API explorer to build and test your requests before deploying them. The explorer will automatically generate a basic connection script in the most common coding languages to get you up and running quickly.

Syntax for requests

https://{USERNAME}:{PASSWORD}@www.nutritics.com/api/{API_VERSION}/{FUNCTION}/user={USER_ID}&{OBJECT}={ID OR GROUP}&[other parameters...]

Parameters after the last forward slash can be listed in any order.

Please note, the following characters are in use by the API engine and may break certain requests:
{ ' } / \ | ¦ ~ > < + - , : " [ ]

Request Methods

Nutritics API supports both HTTP GET and HTTP POST methods. For simplicity, the GET method is used throughout our documentation. Please note however that HTML GET maximum URL length is 2048 characters so you will need to use the POST method if you need to make very long requests.

Required Parameters

The following parameters are required on all requests.

{USERNAME}:{PASSWORD}

Your developer username & Password

{API_VERSION}

Currently v1.1

{FUNCTION}

The action you wish to perform. Read more about functions.
function description
LIST Search and retrieve a list of Nutritics Objects or any set of data within them
CREATE Create a new Nutritics Object and return it's calculated values
MODIFY Edit a Nutritics Object
DELETE Remove a Nutritics Object

{OBJECT}

The type of data you wish to work with. A description of each of our core objects is listed below. Read more about objects.

object parent description
user dev A Nutritics account
client user A customer of a Nutritics user
food user A base food or ingredient
recipe user Multiple foods are combined to form a recipe
activity system An exercise or physical action
dietlog client A list of foods a client has eaten over a given period
mealplan client A special diet prescribed by a user for their client

Return Data

All requests return a stripped Nutritics object in JSON format. The following attributes are appended to all returned objects

Attribute Type description
status int(3)int: A numeric value without a decimal Response code of your request
msg stringstring: Letters, numbers, or other types of characters A message containing errors or warnings regarding your request.
queryTime intint: A numeric value without a decimal Number of miliseconds the server took to process your request
id intint: A numeric value without a decimal Returned only with 404 errors to specify the nutritics ID of the missing component.
warning stringstring: Letters, numbers, or other types of characters Returned only when something has gone wrong but your request was still processed successfully.

Debugging

You may append &debug=1 to any request to see a breakdown of all the data the API is using to calculate its response to your request. This can give useful insight when debugging your application.

Authentication

Authenticating Your Requests

To authenticate your developer account, simply send your username & password in the request URL.

For example, here's a simple request which searches our database for the keyword "bananna" https://[USERNAME]:[PASSWORD]@https://www.nutritics.com/api/v1.1/LIST/food=bananna

Accessing user data

To access another user's data, your app must first be granted access by that user to the specific resource(s) you require. This is done by launching a popup window in the users browser which allows them to sign in and approve your app for the resources you need.

User's have full control of app permissions and may revoke access at any time. With this in mind, it's important to check for permissions each time the user wishes to use your app.

https://[USERNAME]:[PASSWORD]@https://www.nutritics.com/api/v1.1/LIST/food=bananna

Nutritics Objects

Data is sent and received from the API in Nutritics objects. The tables below show all available attributes for each Nutritics object. Note that all API functions return a stripped object, which will not contain all available attributes. If you need some attributes which are not returned by default, simply add a list of required attribute names in the attr parameter. Your developer account must be cleared by Nutritics staff to retrieve cetrain attributes.

  • Foods
  • Recipes
  • Clients
  • Diet Logs
  • Meal Plans
  • Nutrients
  • Portions
  • Components
  • Special
Attribute Permission Type Unit Description Group Default for:
id Read int(10)int: A numeric value without a decimal Nutritics internal ID System LIST/DETAIL
id2 Read int(20)int: A numeric value without a decimal id2 System
moddate Read datedate: A timestamp in unix timestamp format for inputs or Y-M-D H:M:S format for outputs The last modified date and time of this object in the UTC or GMT timezone System LIST/DETAIL
userID Read int(10)int: A numeric value without a decimal ID of the owner of this object System LIST/DETAIL
interID Read int(10)int: A numeric value without a decimal Groups the same foods from different countries System
foodlabel Read list of arrayslist of arrays: A list of array objects, separated by commas, each containing multiple variables. EU food label data including traffic light colours System
portions Read list of arrayslist of arrays: A list of array objects, separated by commas, each containing multiple variables. List of available portions for this food System
notes Read/Write stringstring: Letters, numbers, or other types of characters
costs Read arrayarray: A package containing multiple variables, usually containing internal labels for each How much the selected user pays for this food System
allergens Read list of arrayslist of arrays: A list of array objects, separated by commas, each containing multiple variables.
cmethod Read arrayarray: A package containing multiple variables, usually containing internal labels for each cmethod System
customfields Read arrayarray: A package containing multiple variables, usually containing internal labels for each Populatable only via the Nutritics front-end, this custom data can be retrieved through the API System
ifc Read string(17)string: Letters, numbers, or other types of characters (International Food Code) Universally unique identifier Categorisation LIST/DETAIL
src Read string(6)string: Letters, numbers, or other types of characters Identifier for source database Categorisation LIST/DETAIL
code Read/Write string(20)string: Letters, numbers, or other types of characters Owner's Food identifier (product code, item number, etc).... Categorisation LIST/DETAIL
* cat (Required) Read/Write string(33)string: Letters, numbers, or other types of characters Nutritics standardised food category (see HELP function for a list of available categories) Categorisation LIST/DETAIL
groups Read/Write array(65535)array: A package containing multiple variables, usually containing internal labels for each List of folders or labels the owner has tagged to this object Categorisation
name Read/Write string(130)string: Letters, numbers, or other types of characters Name of this object Properties LIST/DETAIL
description Read/Write string(255)string: Letters, numbers, or other types of characters Optional description of this object Properties DETAIL
storage Read/Write string(255)string: Letters, numbers, or other types of characters Text instructions for storing this recipe Properties DETAIL
quantity Read arrayarray: A package containing multiple variables, usually containing internal labels for each Quantity Properties DETAIL
isRecipe Read boolean(1)boolean: A true or false variable Is Recipe (1=yes) Properties
completeScore Read string(10)string: Letters, numbers, or other types of characters An indicator of how complete this food is. KEY: category-label-allergens-primary-extended Properties
authorRank Read int(3)int: A numeric value without a decimal The rank of the user who entered this food at the time of publication of the food Properties
p1 Read/Write stringstring: Letters, numbers, or other types of characters
q1 Read/Write stringstring: Letters, numbers, or other types of characters
p2 Read/Write stringstring: Letters, numbers, or other types of characters
q2 Read/Write stringstring: Letters, numbers, or other types of characters
p3 Read/Write stringstring: Letters, numbers, or other types of characters
q3 Read/Write stringstring: Letters, numbers, or other types of characters
p4 Read/Write stringstring: Letters, numbers, or other types of characters
q4 Read/Write stringstring: Letters, numbers, or other types of characters
p5 Read/Write stringstring: Letters, numbers, or other types of characters
q5 Read/Write stringstring: Letters, numbers, or other types of characters
csvurl Read formulaformula: DETAIL
reporturl Read formulaformula: LIST/DETAIL
photo Read formulaformula: LIST/DETAIL
gluten Read/Write intint: A numeric value without a decimal Cereals Containing Gluten Allergens
wheat Read/Write intint: A numeric value without a decimal Wheat Allergens
oats Read/Write intint: A numeric value without a decimal Oats Allergens
barley Read/Write intint: A numeric value without a decimal Barley Allergens
rye Read/Write intint: A numeric value without a decimal Rye Allergens
milk Read/Write intint: A numeric value without a decimal Milk Allergens
eggs Read/Write intint: A numeric value without a decimal Eggs Allergens
fish Read/Write intint: A numeric value without a decimal Fish Allergens
crustaceans Read/Write intint: A numeric value without a decimal Crustaceans Allergens
molluscs Read/Write intint: A numeric value without a decimal Molluscs Allergens
peanuts Read/Write intint: A numeric value without a decimal Peanuts Allergens
nuts Read/Write intint: A numeric value without a decimal Tree Nuts Allergens
hazelnuts Read/Write intint: A numeric value without a decimal Hazelnuts Allergens
almonds Read/Write intint: A numeric value without a decimal Almonds Allergens
cashews Read/Write intint: A numeric value without a decimal Cashews Allergens
walnut Read/Write intint: A numeric value without a decimal Walnuts Allergens
pecan Read/Write intint: A numeric value without a decimal Pecans Allergens
brazil Read/Write intint: A numeric value without a decimal Brazil Nuts Allergens
pistachio Read/Write intint: A numeric value without a decimal Pistachio Nuts Allergens
macadamia Read/Write intint: A numeric value without a decimal Macadamia Nuts Allergens
sesame Read/Write intint: A numeric value without a decimal Sesame Allergens
mustard Read/Write intint: A numeric value without a decimal Mustard Allergens
celery Read/Write intint: A numeric value without a decimal Celery Allergens
soya Read/Write intint: A numeric value without a decimal Soya Allergens
lupin Read/Write intint: A numeric value without a decimal Lupin Allergens
sulphites Read/Write intint: A numeric value without a decimal Sulphites Allergens
vegetarian Read/Write boolean(1)boolean: A true or false variable Vegetarian (1=yes) Dietary Preferences
vegan Read/Write boolean(1)boolean: A true or false variable Vegan (1=yes) Dietary Preferences
halal Read/Write boolean(1)boolean: A true or false variable Halal (1=yes) Dietary Preferences
glutenfree Read/Write boolean(1)boolean: A true or false variable Gluten Free (1=yes) Dietary Preferences
kosher Read/Write boolean(1)boolean: A true or false variable Kosher (1=yes) Dietary Preferences
energyKcal Read/Write float(12)float: A numeric value which can contain a decimal kcal Energy kcal Energy DETAIL
energyKj Read/Write float(12)float: A numeric value which can contain a decimal kJ Energy kJ Energy DETAIL
carbohydrate Read/Write float(12)float: A numeric value which can contain a decimal g CHO is by weight (UK/EU) or by difference (US) at 4kcal per gram Macronutrients DETAIL
protein Read/Write float(12)float: A numeric value which can contain a decimal g Protein Macronutrients DETAIL
fat Read/Write float(12)float: A numeric value which can contain a decimal g Fat Macronutrients DETAIL
water Read/Write float(12)float: A numeric value which can contain a decimal g Water (Moisture) Macronutrients DETAIL
waterDr Read float(12)float: A numeric value which can contain a decimal g Water from Drinks Macronutrients DETAIL
alcohol Read/Write float(12)float: A numeric value which can contain a decimal g Alcohol Macronutrients
starch Read/Write float(12)float: A numeric value which can contain a decimal g Starch Carbohydrate Components DETAIL
oligosaccharide Read/Write float(12)float: A numeric value which can contain a decimal g Includes maltodextrins, fructooligosaccharides,maltotriose (in beer), inulin Carbohydrate Components
sugars Read/Write float(12)float: A numeric value which can contain a decimal g Sugars Carbohydrate Components DETAIL
freesugars Read float(12)float: A numeric value which can contain a decimal g Often called added sugar on labels Carbohydrate Components DETAIL
sucrose Read/Write float(12)float: A numeric value which can contain a decimal g Sucrose Carbohydrate Components
glucose Read/Write float(12)float: A numeric value which can contain a decimal g Glucose Carbohydrate Components
lactose Read/Write float(12)float: A numeric value which can contain a decimal g lactose Carbohydrate Components
fructose Read/Write float(12)float: A numeric value which can contain a decimal g Fructose Carbohydrate Components
galactose Read/Write float(12)float: A numeric value which can contain a decimal g Galactose Carbohydrate Components
maltose Read/Write float(12)float: A numeric value which can contain a decimal g maltose Carbohydrate Components
nsp Read/Write float(12)float: A numeric value which can contain a decimal g NSP (Englyst) Carbohydrate Components DETAIL
fibre Read/Write float(12)float: A numeric value which can contain a decimal g Fibre Carbohydrate Components DETAIL
satfat Read/Write float(12)float: A numeric value which can contain a decimal g Saturated Fat Fat Components DETAIL
monos Read/Write float(12)float: A numeric value which can contain a decimal g Monounsaturated Fat Fat Components
poly Read/Write float(12)float: A numeric value which can contain a decimal g Polyunsaturated Fat Fat Components
n3poly Read/Write float(12)float: A numeric value which can contain a decimal g Omega-3 (Total) Fat Components
n6poly Read/Write float(12)float: A numeric value which can contain a decimal g Omega-6 (Total) Fat Components
trans Read/Write float(12)float: A numeric value which can contain a decimal g Trans Fats (Total) Fat Components
cholesterol Read/Write float(12)float: A numeric value which can contain a decimal mg Cholesterol Fat Components
vita Read/Write float(12)float: A numeric value which can contain a decimal ug carotene/6 + retinol = Vitamin A Vitamins
retinol Read/Write float(12)float: A numeric value which can contain a decimal ug Retinol (preformed) Vitamins
carotene Read/Write float(12)float: A numeric value which can contain a decimal ug Beta carotene + alpha carotene x.5 + beta cryptoxanthins x .5 Vitamins
vitd Read/Write float(12)float: A numeric value which can contain a decimal ug Vitamin D3 (cholecalciferol) + Vitamin D2 (ergocalciferol) +(25OHD3)x5 Vitamins
vite Read/Write float(12)float: A numeric value which can contain a decimal mg as alpha toceopherol equivalents (factors in M&W p14) Vitamins
vitk Read/Write float(12)float: A numeric value which can contain a decimal ug Vitamin K1 (Phylloquinone) Vitamins
thiamin Read/Write float(12)float: A numeric value which can contain a decimal mg Thiamin (B1) Vitamins
riboflavin Read/Write float(12)float: A numeric value which can contain a decimal mg Riboflavin (B2) Vitamins
niacin Read/Write float(12)float: A numeric value which can contain a decimal mg The sum of nicotinic acid and nicotinaminde Vitamins
niacineqv Read/Write float(12)float: A numeric value which can contain a decimal mg Niacin + tryptophan/60 Vitamins
pantothenate Read/Write float(12)float: A numeric value which can contain a decimal mg Pantothenate (B5) Vitamins
vitb6 Read/Write float(12)float: A numeric value which can contain a decimal mg Vitamin B6 (Pyridoxine) Vitamins
biotin Read/Write float(12)float: A numeric value which can contain a decimal ug Biotin (B7) Vitamins
folate Read float(12)float: A numeric value which can contain a decimal ug Total Folates Vitamins DETAIL
folateDFE Read float(12)float: A numeric value which can contain a decimal ug Total Folates+1.7 folic acid (synthetic) Vitamins DETAIL
vitb12 Read/Write float(12)float: A numeric value which can contain a decimal ug Vitamin B12 (Cobalamin) Vitamins
vitb12Fortified Read/Write float(12)float: A numeric value which can contain a decimal ug Vitamin B12 (Synthetic) Vitamins
vitc Read/Write float(12)float: A numeric value which can contain a decimal mg Vitamin C Vitamins DETAIL
sodium Read/Write float(12)float: A numeric value which can contain a decimal mg Sodium (Na) Minerals & Trace Elements DETAIL
salt Read/Write float(12)float: A numeric value which can contain a decimal g Salt Minerals & Trace Elements
potassium Read/Write float(12)float: A numeric value which can contain a decimal mg Potassium (K) Minerals & Trace Elements
calcium Read/Write float(12)float: A numeric value which can contain a decimal mg Calcium (Ca) Minerals & Trace Elements
magnesium Read/Write float(12)float: A numeric value which can contain a decimal mg Magnesium (Mg) Minerals & Trace Elements
phosphorus Read/Write float(12)float: A numeric value which can contain a decimal mg Phosphorus (P) Minerals & Trace Elements
iron Read/Write float(12)float: A numeric value which can contain a decimal mg Iron (Fe) Minerals & Trace Elements
copper Read/Write float(12)float: A numeric value which can contain a decimal mg Copper (Cu) Minerals & Trace Elements
zinc Read/Write float(12)float: A numeric value which can contain a decimal mg Zinc (Zn) Minerals & Trace Elements
chloride Read/Write float(12)float: A numeric value which can contain a decimal mg Chloride (Cl) Minerals & Trace Elements DETAIL
selenium Read/Write float(12)float: A numeric value which can contain a decimal ug Selenium (Se) Minerals & Trace Elements
iodine Read/Write float(12)float: A numeric value which can contain a decimal ug Iodine (I) Minerals & Trace Elements
nitrogen Read/Write float(12)float: A numeric value which can contain a decimal g Nitrogen Other DETAIL
caffeine Read float(12)float: A numeric value which can contain a decimal mg Caffeine Other
gi Read/Write float(12)float: A numeric value which can contain a decimal Glycemic Index Glycemic Impact
gl Read/Write float(12)float: A numeric value which can contain a decimal Glycemic Load Glycemic Impact
polyols Read/Write float(12)float: A numeric value which can contain a decimal g Formerly excluded erythritol. Now interchangeable with polyols Sugar Alcohols DETAIL
tryptophan Read/Write float(12)float: A numeric value which can contain a decimal mg Tryptophan Amino Acids
Attribute Access Data Type Description Default
id Read int(10)int: A numeric value without a decimal Nutritics internal ID LIST/DETAIL
id2 Read int(20)int: A numeric value without a decimal DETAIL
moddate Read datedate: A timestamp in unix timestamp format for inputs or Y-M-D H:M:S format for outputs The last modified date and time of this object in the UTC or GMT timezone LIST/DETAIL
userID Read int(10)int: A numeric value without a decimal ID of the creator / owner of this object LIST/DETAIL
quid Read string(65535)string: Letters, numbers, or other types of characters A legislation-compliant ingredient declaration in HTML format for product packaging
foodlabel Read list of arrayslist of arrays: A list of array objects, separated by commas, each containing multiple variables. EU food label data including traffic light colours
portions Read list of arrayslist of arrays: A list of array objects, separated by commas, each containing multiple variables. List of all available portion sizes for this recipe
notes Read/Write stringstring: Letters, numbers, or other types of characters
costs Read arrayarray: A package containing multiple variables, usually containing internal labels for each Cost and RRP for this recipe, auto-calculated from ingredient costs
claims Read arrayarray: A package containing multiple variables, usually containing internal labels for each
allergens Read list of arrayslist of arrays: A list of array objects, separated by commas, each containing multiple variables. Allergens and dietary properties, grouped by type
components Read/Write list of arrayslist of arrays: A list of array objects, separated by commas, each containing multiple variables. Ingredients for this recipe
cmethod Read arrayarray: A package containing multiple variables, usually containing internal labels for each cmethod
customfields Read arrayarray: A package containing multiple variables, usually containing internal labels for each Populatable only via the Nutritics front-end, this custom data can be retrieved through the API
ifc Read string(17)string: Letters, numbers, or other types of characters (International Food Code) Universally unique identifier LIST/DETAIL
code Read/Write string(20)string: Letters, numbers, or other types of characters Owner's Food identifier (product code, item number, etc) DETAIL
cat Read/Write string(33)string: Letters, numbers, or other types of characters Nutritics standardised food category (see HELP function for a list of available categories) LIST
src Read string(6)string: Letters, numbers, or other types of characters Source database of this recipe LIST/DETAIL
groups Read/Write array(65535)array: A package containing multiple variables, usually containing internal labels for each List of folders or labels the owner has tagged to this object
name Read/Write string(130)string: Letters, numbers, or other types of characters Name of this object LIST/DETAIL
description Read/Write string(255)string: Letters, numbers, or other types of characters Optional description of this object DETAIL
totalRecipeWeight Read intint: A numeric value without a decimal The total weight of all recipe ingredients before weightloss from cooking
weightAfterCooking Read formulaformula: DETAIL
portionCount Read/Write int(12)int: A numeric value without a decimal The total number of portions this recipe serves DETAIL
recipeConversionFactor Read/Write float(12)float: A numeric value which can contain a decimal Optional: Recipe yield factor: The total weight of ingredients divided by their total weight after cooking. For example, if a recipe is 20% lighter after cooking, enter 0.8 in this field. DETAIL
liquid Read/Write boolean(1)boolean: A true or false variable Is this recipe a liquid?
shelfLife Read/Write string(255)string: Letters, numbers, or other types of characters Text instructions for expiry of this food DETAIL
storage Read/Write string(255)string: Letters, numbers, or other types of characters Text instructions for storing this food DETAIL
quantity Read arrayarray: A package containing multiple variables, usually containing internal labels for each DETAIL
isRecipe Read boolean(1)boolean: A true or false variable
p1 Read/Write stringstring: Letters, numbers, or other types of characters
q1 Read/Write stringstring: Letters, numbers, or other types of characters
p2 Read/Write stringstring: Letters, numbers, or other types of characters
q2 Read/Write stringstring: Letters, numbers, or other types of characters
p3 Read/Write stringstring: Letters, numbers, or other types of characters
q3 Read/Write stringstring: Letters, numbers, or other types of characters
p4 Read/Write stringstring: Letters, numbers, or other types of characters
q4 Read/Write stringstring: Letters, numbers, or other types of characters
p5 Read/Write stringstring: Letters, numbers, or other types of characters
q5 Read/Write stringstring: Letters, numbers, or other types of characters
csvurl Read formulaformula: DETAIL
reporturl Read formulaformula: LIST/DETAIL
photo Read formulaformula: LIST/DETAIL
gluten Read/Write intint: A numeric value without a decimal Cereals Containing Gluten
wheat Read/Write intint: A numeric value without a decimal Wheat
oats Read/Write intint: A numeric value without a decimal Oats
barley Read/Write intint: A numeric value without a decimal Barley
rye Read/Write intint: A numeric value without a decimal Rye
milk Read/Write intint: A numeric value without a decimal Milk
eggs Read/Write intint: A numeric value without a decimal Eggs
fish Read/Write intint: A numeric value without a decimal Fish
crustaceans Read/Write intint: A numeric value without a decimal Crustaceans
molluscs Read/Write intint: A numeric value without a decimal Molluscs
peanuts Read/Write intint: A numeric value without a decimal Peanuts
nuts Read/Write intint: A numeric value without a decimal Tree Nuts
hazelnuts Read/Write intint: A numeric value without a decimal Hazelnuts
almonds Read/Write intint: A numeric value without a decimal Almonds
cashews Read/Write intint: A numeric value without a decimal Cashews
walnut Read/Write intint: A numeric value without a decimal Walnuts
pecan Read/Write intint: A numeric value without a decimal Pecans
brazil Read/Write intint: A numeric value without a decimal Brazil Nuts
pistachio Read/Write intint: A numeric value without a decimal Pistachio Nuts
macadamia Read/Write intint: A numeric value without a decimal Macadamia Nuts
sesame Read/Write intint: A numeric value without a decimal Sesame
mustard Read/Write intint: A numeric value without a decimal Mustard
celery Read/Write intint: A numeric value without a decimal Celery
soya Read/Write intint: A numeric value without a decimal Soya
lupin Read/Write intint: A numeric value without a decimal Lupin
sulphites Read/Write intint: A numeric value without a decimal Sulphites
vegetarian Read/Write boolean(1)boolean: A true or false variable Vegetarian (1=yes)
vegan Read/Write boolean(1)boolean: A true or false variable Vegan (1=yes)
halal Read/Write boolean(1)boolean: A true or false variable Halal (1=yes)
glutenfree Read/Write boolean(1)boolean: A true or false variable Gluten Free (1=yes)
kosher Read/Write boolean(1)boolean: A true or false variable Kosher (1=yes)
energyKcal Read float(12)float: A numeric value which can contain a decimal Energy kcal DETAIL
energyKj Read float(12)float: A numeric value which can contain a decimal Energy kJ DETAIL
carbohydrate Read float(12)float: A numeric value which can contain a decimal CHO is by weight (UK/EU) or by difference (US) at 4kcal per gram DETAIL
protein Read float(12)float: A numeric value which can contain a decimal Protein DETAIL
fat Read float(12)float: A numeric value which can contain a decimal Fat DETAIL
water Read float(12)float: A numeric value which can contain a decimal Water DETAIL
waterDr Read float(12)float: A numeric value which can contain a decimal Water from Drinks DETAIL
alcohol Read float(12)float: A numeric value which can contain a decimal Alcohol
starch Read float(12)float: A numeric value which can contain a decimal Starch DETAIL
oligosaccharide Read float(12)float: A numeric value which can contain a decimal Includes maltodextrins, fructooligosaccharides,maltotriose (in beer), inulin
sugars Read float(12)float: A numeric value which can contain a decimal Sugars DETAIL
freesugars Read float(12)float: A numeric value which can contain a decimal Often called added sugar on labels DETAIL
sucrose Read float(12)float: A numeric value which can contain a decimal Sucrose
glucose Read iptiption(12)iptiption: Glucose
lactose Read float(12)float: A numeric value which can contain a decimal lactose
fructose Read iptiption(12)iptiption: Fructose
galactose Read iptiption(12)iptiption: Galactose
maltose Read float(12)float: A numeric value which can contain a decimal maltose
nsp Read float(12)float: A numeric value which can contain a decimal NSP (Englyst) DETAIL
fibre Read float(12)float: A numeric value which can contain a decimal Fibre DETAIL
satfat Read float(12)float: A numeric value which can contain a decimal Saturated Fat DETAIL
monos Read float(12)float: A numeric value which can contain a decimal MUFA Monounsaturated Fat
poly Read float(12)float: A numeric value which can contain a decimal PUFA Polyunsaturated Fat
n3poly Read float(12)float: A numeric value which can contain a decimal Omega-3 (Total)
n6poly Read float(12)float: A numeric value which can contain a decimal Omega-6 (Total)
trans Read float(12)float: A numeric value which can contain a decimal Trans Fats (Total)
cholesterol Read float(12)float: A numeric value which can contain a decimal Cholesterol
vita Read float(12)float: A numeric value which can contain a decimal carotene/6 + retinol = Vitamin A
retinol Read float(12)float: A numeric value which can contain a decimal Retinol (preformed)
carotene Read float(12)float: A numeric value which can contain a decimal Beta carotene + alpha carotene x.5 + beta cryptoxanthins x .5
vitd Read float(12)float: A numeric value which can contain a decimal Vitamin D3 (cholecalciferol) + Vitamin D2 (ergocalciferol) +(25OHD3)x5
vite Read float(12)float: A numeric value which can contain a decimal as alpha toceopherol equivalents (factors in M&W p14)
vitk Read float(12)float: A numeric value which can contain a decimal Vitamin K1 Phylloquinone
thiamin Read float(12)float: A numeric value which can contain a decimal Thiamin (B1)
riboflavin Read float(12)float: A numeric value which can contain a decimal Riboflavin (B2)
niacin Read float(12)float: A numeric value which can contain a decimal The sum of nicotinic acid and nicotinaminde
niacineqv Read float(12)float: A numeric value which can contain a decimal Niacin + tryptophan/60
pantothenate Read float(12)float: A numeric value which can contain a decimal Pantothenate (B5)
vitb6 Read float(12)float: A numeric value which can contain a decimal Vitamin B6 (Pyridoxine)
biotin Read float(12)float: A numeric value which can contain a decimal Biotin (B7)
folate Read float(12)float: A numeric value which can contain a decimal Total Folates DETAIL
folateDFE Read float(12)float: A numeric value which can contain a decimal Total Folates (B9) Folic acid *1.7 + natural folate DETAIL
vitb12 Read float(12)float: A numeric value which can contain a decimal Vitamin B12 (Cobalamin)
vitc Read float(12)float: A numeric value which can contain a decimal Vitamin C DETAIL
sodium Read float(12)float: A numeric value which can contain a decimal Sodium (Na) DETAIL
salt Read float(12)float: A numeric value which can contain a decimal Salt
potassium Read float(12)float: A numeric value which can contain a decimal Potassium (K)
calcium Read float(12)float: A numeric value which can contain a decimal Calcium (Ca)
magnesium Read float(12)float: A numeric value which can contain a decimal Magnesium (Mg)
phosphorus Read float(12)float: A numeric value which can contain a decimal Phosphorus (P)
iron Read float(12)float: A numeric value which can contain a decimal Iron (Fe)
copper Read float(12)float: A numeric value which can contain a decimal Copper (Cu)
zinc Read float(12)float: A numeric value which can contain a decimal Zinc (Zn)
chloride Read float(12)float: A numeric value which can contain a decimal Chloride (Cl) DETAIL
manganese Read float(12)float: A numeric value which can contain a decimal Manganese (Mn) DETAIL
selenium Read float(12)float: A numeric value which can contain a decimal Selenium (Se)
iodine Read float(12)float: A numeric value which can contain a decimal Iodine (I)
nitrogen Read float(12)float: A numeric value which can contain a decimal Nitrogen DETAIL
caffeine Read float(12)float: A numeric value which can contain a decimal Caffeine
gi Read iptiption(12)iptiption: Glycemic Index
gl Read iptiption(12)iptiption: Glycemic Load
polyols Read/Write float(12)float: A numeric value which can contain a decimal Formerly excluded erythritol. Now interchangeable with polyols DETAIL
tryptophan Read float(12)float: A numeric value which can contain a decimal Tryptophan
Attribute Access Data Type Default
id Read int(10)int: A numeric value without a decimal LIST/DETAIL
userID Read string(10)string: Letters, numbers, or other types of characters LIST/DETAIL
forename Read/Write stringstring: Letters, numbers, or other types of characters LIST/DETAIL
surname Read/Write stringstring: Letters, numbers, or other types of characters LIST/DETAIL
idno Read/Write stringstring: Letters, numbers, or other types of characters LIST/DETAIL
created Read datedate: A timestamp in unix timestamp format for inputs or Y-M-D H:M:S format for outputs LIST/DETAIL
* gender (Required) Read/Write charchar: A single character in lowercase DETAIL
tel Read/Write stringstring: Letters, numbers, or other types of characters DETAIL
mobile Read/Write stringstring: Letters, numbers, or other types of characters DETAIL
notes Read/Write stringstring: Letters, numbers, or other types of characters
email Read/Write stringstring: Letters, numbers, or other types of characters DETAIL
address Read/Write stringstring: Letters, numbers, or other types of characters DETAIL
* dob (Required) Read/Write datedate: A timestamp in unix timestamp format for inputs or Y-M-D H:M:S format for outputs DETAIL
* weight (Required) Read/Write floatfloat: A numeric value which can contain a decimal DETAIL
* height (Required) Read/Write floatfloat: A numeric value which can contain a decimal DETAIL
waist Read/Write floatfloat: A numeric value which can contain a decimal DETAIL
hips Read/Write floatfloat: A numeric value which can contain a decimal DETAIL
bodyfat Read/Write floatfloat: A numeric value which can contain a decimal DETAIL
formula Read/Write stringstring: Letters, numbers, or other types of characters DETAIL
occ_activity Read/Write intint: A numeric value without a decimal DETAIL
exe_activity Read/Write intint: A numeric value without a decimal DETAIL
athletic Read/Write stringstring: Letters, numbers, or other types of characters DETAIL
pregnancy Read/Write stringstring: Letters, numbers, or other types of characters DETAIL
EERadjust Read/Write intint: A numeric value without a decimal DETAIL
calc_bmi Read floatfloat: A numeric value which can contain a decimal DETAIL
calc_pal Read/Write floatfloat: A numeric value which can contain a decimal DETAIL
calc_bmr Read/Write floatfloat: A numeric value which can contain a decimal DETAIL
calc_energy Read floatfloat: A numeric value which can contain a decimal DETAIL
autopal Read intint: A numeric value without a decimal DETAIL
autobmr Read intint: A numeric value without a decimal DETAIL
groups Read/Write array(65535)array: A package containing multiple variables, usually containing internal labels for each LIST/DETAIL
logcount Read intint: A numeric value without a decimal DETAIL
mealplancount Read intint: A numeric value without a decimal DETAIL
drv Read formulaformula:
country Read/Write stringstring: Letters, numbers, or other types of characters LIST/DETAIL
EERadjustRatio Read/Write intint: A numeric value without a decimal DETAIL
sendInvite Read/Write boolean(1)boolean: A true or false variable

Components are sub-elements of objects. They are usually food or recipe objects themselves. On recipes, each ingredient is a component. On logs and meal plans, each food eaten is a component.

Components for recipe objects: (ingredients)

field type required description example
id intint: A numeric value without a decimal or stringstring: Letters, numbers, or other types of characters required ID that identifies the component instance of a food or recipe object ,id:12367
foodID intint: A numeric value without a decimal or stringstring: Letters, numbers, or other types of characters required ID or IFC of a Nutritics food or recipe object ,foodID:GB15.65502
quantity int *int: A numeric value without a decimal This is a special field. Click to see possible values. or string *string: Letters, numbers, or other types of characters This is a special field. Click to see possible values. required Special field. See possible values ,quantity:568
name stringstring: Letters, numbers, or other types of characters optional Overwrites the default food or recipe name with your own name for this ingredient ,name:A pint of warm water
cmethod int *int: A numeric value without a decimal This is a special field. Click to see possible values. or string *string: Letters, numbers, or other types of characters This is a special field. Click to see possible values. optional Specifies the ID or a generic cooking method for this ingredient. Acceptable cooking methods vary for each ingredient. You can look up available cooking methods for a specific food using the DETAIL function. Alternatively pass a generic ID or string, which will attempt to set the cooking method for you automatically. If the method cannot be found, no cooking method will be applied and a warning will be returned in the msg attribute of the response. ,cmethod:Cooked by moist heat

Components for log objects:

Coming Soon...

Components for mealplan objects:

Coming Soon...

The following tables list all possible values for special input fields. These values can be used in multiple functions.

ID Fields

All id fields on all functions accept the following values

format description example
[int] ID: Nutritics internal ID 200134
[dbsrc].[foodcode] IFC: International Food Code. Note: IFC for all user-created foods and recipes begins with U. GB15.65502
_[int] Barcode: Look up a food by its UPC-A barcode by prepending an underscore _51665834

Quantity Fields

All quantity fields on all functions accept the following values. Please note the minimum accepted quantity is 0.01g.

format description example
[int] Weight in grams 450
[num][unit] Weight in one of the following units: g, kg, lb, oz, st, ml, l, floz, pt, qt, gl 2lb 1oz
"p"[int] User's portions 1-5 (if available) p2
[num]"x" Attempts to find [num] units of the food. For example "2x" used with Apples, would find 2 average sized apples while "2x" on bread would find 2 average slices. [beta] 3x
RECIPE OBJECTS ONLY
"serving" Weight of one serving (available only when portionCount is set in the recipe) serving
"total" Weight of the entire recipe (if available) total

Filter Field

Use the filter field on a LIST function to run a Nutritics search. The search engine accepts the following optional parameters:

format description example
[string] Search Term: A word or phrase to search our database. This must be passed before any of the parameters below. bananna
attr:[string] Attribute: Search by one or more object attributes. Most attributes from a Nutritics Object are accepted. Separate multiple attributes by spaces. Separate multiple attribute values by commas. You may use > or < operators for numeric attributes. Boolean attributes should be specified in binary format cat:Pastas,Rice vita:>100,<200 gluten:0
shared:[bool] Special Flag: If specified, this flag returns only objects shared with the selected user. You may also pass a -1 here to return both the user's own objects and objects shared with them. shared:1
order:[string] Sort Order: Specify an attribute to order the result list. order:vitc DESC
FOOD & RECIPE OBJECTS ONLY
src:[string] Data Source: ISO Alpha2 country code or specific database code(s) to search within (Defaults to the setting on your develeoper account) src:IE09,GB15
FOOD OBJECTS ONLY
like:[id or ifc] Similar Foods: List foods similar to the selected food like:GB15.4016

Example Requests

Find fruits from the default American datasets which have the most vitamin C:

https://[USERNAME]:[PASSWORD]@www.nutritics.com/api/v1.1/LIST/food=cat:fruits order:vitc DESC src:US

Get a list of IDs for a user's recipes which have been modified since Jun 20th 2017 @ 10:50:02 UTC:

https://[USERNAME]:[PASSWORD]@www.nutritics.com/api/v1.1/LIST/userID=3&recipe=moddate:>1497955802&attr=id

Prefs Field

Use the prefs field on a LIST function override the settings on your developer account temporarily for a specific request. Note: You can change your default settings using the ADMIN function

format description example
labelFormat:[string] Label Format: Labelling region (EU, US or AU). Changes the legislation used to generate label data. labelFormat:AU

Cooking Methods

cmethod fields on recipe components may accept the one following values (passed in ID or string format). However since acceptable cooking methods vary for each ingredient, we recommend looking up available cooking methods for each specific food using cmethod attribute on the LIST function. The list below is in order of popularity and the first three items are available to 90% of foods. If you pass a method which cannot be applied to the specified food, the Nutitics engine will automatically find and apply the closest match. If no match is found or an unrecognised cooking method is passed, the request will proceed as normal and a warning will be returned within the response data.

  1. Cooked by dry heat
  2. Cooked by moist heat
  3. Cooked with fat or oil (baked/fried) *
  4. Sauteed/Stir-fried in oil
  5. Baked or roasted
  6. Deep fried in oil *
  7. Boiled in salted water *
  8. Batter/crumbed, deep fried in oil *
  9. Stewed
  10. Batter/crumbed, baked in oil *
  11. Batter/crumbed, pan fried in oil *
  12. Crumbed, baked without oil
  13. Broiled or grilled
  14. Boiled or steamed
  15. Boiled
  16. Cooked with fat or oil (fried), with sauce *
  17. Cooked by dry heat, with sauce
  18. Cooked by moist heat, with sauce
  19. Stewed or braised
  20. Steamed
  21. Flash Fried *
  22. Stewed, braised, with sauce
  23. Boiled, steamed, with sauce
  24. Juiced Ingredient
  25. Steeped
  26. As Dish with sauce, Cooked by moist heat
  27. Toasted
  28. Cooked by moist heat, with cooking liquid
  29. Jam, Jelly, Marmalade
  30. Boiled - wholegrain
  31. As Dish, Cooked by dry heat
  32. As Dish with sauce, Cooked with fat or oil (baked/fried)
  33. Used as flour / light dusting only
  34. Used as a batter or coating, fried in oil
  35. Boiled, not drained
  36. As Dish, Cooked by moist heat
  37. As Dish with sauce, Cooked by dry heat
  38. Blended Ingredient
  39. Used as a batter or coating, baked or dry heat
  40. Boiled, drained
  41. Cooked with fat or oil (baked/fried), with sauce *
  42. Cooked with heat <15 minutes (40% alcohol losses)
  43. Boiled in salted water (polished grain) - water absorbed *
  44. Added to cooking water
  45. In Pancake *
  46. Cooked with fat or oil *
  47. As Dish, Deep fried in oil *
  48. Boiled in salted water (wholegrain) - water absorbed *
  49. Scrambled / Sauteed
  50. As Dish, Sauteed/Stir-fried in oil *
  51. Cooked with heat >45 minutes (90% alcohol losses)
  52. Used as a medium for frying or deep frying ingredients
  53. Boiled in salted water (polished grain)- water drained *
  54. Fried *
  55. Boiled, with cooking liquid
  56. As Dish, Cooked with fat or oil (baked/fried) *
  57. Deep fried in fat or oil *
  58. Cooked with heat 15-45 minutes (80% alcohol losses)
  59. Used as a medium for baking, grilling or roasting ingredients
  60. Boiled in salted water (wholegrain)- water drained *
  61. Boiled - polished grain
  62. As Dish, Broiled or grilled
  63. Used as batter or coating - fried in oil
  64. Fat fully incorporated into recipe
  65. Boiled, in salted water *
  66. Boiled in dish / sauce
  67. As Dish, Baked or roasted
  68. Used as batter or coating - baked or dry heat


* This cooking method requires any fat to be added as an extra ingredient with one of the cooking methods shown in orange
* This cooking method requires any salt to be added as an extra ingredient with one of the cooking methods shown in blue
* This cooking method requires a sub-recipe to be added as an extra ingredient with one of the cooking methods shown in gold

Example:

...[id:GB15.63832,quantity:496g,name:4 cups of flour,cmethod:Toasted]...

When passing the component above on CREATE OR MODIFY, since the cooking method 'Toasted' is not available for flours, Nutritics will apply the more generic method: 'Cooked by dry heat'

Food Categories

All new food objects must be assigned to one of the following food categories

https://www.nutritics.com/api/v1.1/HELP/food&cats

Datasets

The following database sources are acceptable for LIST functions.

https://www.nutritics.com/api/v1.1/HELP/food&srcs

Data Types

Data Type List

Special Fields Definition (to be moved to Nutritics Objects Tables dropdowns)

cat: category definition.cat1,cat2,cat3

allergens: allergens definition.freefrom,maycontain,contains,suitablefor.{allergenlist}

Traffic Lights

Functions

  • LIST
  • DETAIL
  • CREATE
  • MODIFY
  • DELETE
  • ADMIN
  • HELP

LIST is a universal function for fetching data on Nutritics. Search our database and retrieve a list of stripped nutritics objectsA stripped object contains only certain important values by default. To obtain specific values, use the attr parameter.. This function searches within the data sources specificed in your dev account, which can be modified using ADMIN.

Parameters

field type required description example
{object} stringstring: Letters, numbers, or other types of characters required The name of any type of Nutritics object &food
user intint: A numeric value without a decimal or listlist: A list of variables, usually ints or strings, separated by commas. optional List all objects owned by a specific user or list of users. Defaults to the 'defaultUser' if set on your developer account, or all authorised users on your developer account if not. &user=123,321
attr listlist: A list of variables, usually ints or strings, separated by commas. optional A list of attributes you wish to return. Any attributes from a Nutritics Object are accepted. Your developer account must be cleared by Nutritics staff to retrieve cetrain attributes. &attr=vitc,vitd,quid
limit stringstring: Letters, numbers, or other types of characters optional Offset and count for pagination of results. Works like SQL limits. This example returns records from 11-31 &limit=11,20
FOOD, RECIPE & CLIENT OBJECTS ONLY:
{filter} array *array: A package containing multiple variables, usually containing internal labels for each This is a special field. Click to see possible values. optional A search term, optionally including filter field parameters &food=coffee
FOOD & RECIPE OBJECTS ONLY:
quantity int *int: A numeric value without a decimal This is a special field. Click to see possible values. or string *string: Letters, numbers, or other types of characters This is a special field. Click to see possible values. required Special field indicating the physical weight/amount you wish to retrieve data for. See accepted values &quantity=100
prefs array *array: A package containing multiple variables, usually containing internal labels for each This is a special field. Click to see possible values. optional Change your preferences for this specific request. Defaults to the settings on your account. See available preferences &prefs=labelFormat:AU

Return Data

Returns an array of stripped Nutritics objects matching the search filter. One additional attribute 'resultCount' is appended to the array which shows the total number of matching results of your search.

Syntax

https://{username}:{password}@www.nutritics.com/api/v1.1/LIST/{object}={filter}&user={user}&attr={attributes}&quantity={quantity}&prefs={prefs}&limit={offset},{count}

Example Requests

Return all foods matching the phrase "red pepper":

https://[USERNAME]:[PASSWORD]@www.nutritics.com/api/v1.1/LIST/food=red pepper

Return the first 3 foods in the "sauces" category:

https://[USERNAME]:[PASSWORD]@www.nutritics.com/api/v1.1/LIST/food=cat:sauces&limit=0,3

Return allergens, portions & ingredients from recipe with id 123456:

https://[USERNAME]:[PASSWORD]@www.nutritics.com/api/v1.1/LIST/recipe=123456&attr=allergens,portions,ingredients

Return nutriton label data for all recipes owned by user 123:

https://[USERNAME]:[PASSWORD]@www.nutritics.com/api/v1.1/LIST/user=123&recipe&attr=foodlabel

DETAIL was depreciated July 13th 2017 and LIST was upgraded to absorb all of its features. We will continue to support DETAIL requests for as long as v1.1 is live.

Retrieve full detail for a specific Nutritics object. The running DETAIL on a food or recipe returns a stripped object which may not contain all the data you are looking for. In this case, use the filters param to specify the data you need.

Parameters

field type required description example
object stringstring: Letters, numbers, or other types of characters required The name of any type of Nutritics object &recipe
id intint: A numeric value without a decimal or stringstring: Letters, numbers, or other types of characters required The ID or IFC of the object you wish to retrieve &recipe=123
attr listlist: A list of variables, usually ints or strings, separated by commas. optional A list of attributes you wish to return. Any attribute from a Nutritics Object is accepted &attr=vitc,vitd,quid
FOOD & RECIPE OBJECTS ONLY:
quantity int *int: A numeric value without a decimal This is a special field. Click to see possible values. or string *string: Letters, numbers, or other types of characters This is a special field. Click to see possible values. required Special field. See accepted values &quantity=100

Return Data

Returns a single Nutritics Object matching the query

Syntax

https://{username}:{pasword}@www.nutritics.com/api/v1.1/DETAIL/{object}={id}&attr={attr1,attr2...}&quantity={quantity}

Example Request

Return allergens, portions & ingredients from recipe with id 123456:

https://[USERNAME]:[PASSWORD]@www.nutritics.com/api/v1.1/LIST/recipe=123456&attr=allergens,portions,ingredients

Create a new Nutritics object from a list of fields or sub-objects and have new values automatically calculated.

Parameters

field type required description example
{object} stringstring: Letters, numbers, or other types of characters required The name of any type of Nutritics object &client
{attributes} multiplemultiple: Multiple variables in the form &attribute=value required Add data for the object creation (See Nutritics Objects for available attributes) &weight=60
user intint: A numeric value without a decimal optional Specify the ID of the user account you wish to create within. Defaults to the 'defaultUser' if set on your developer account, or your developer account itself if not. &user=12345
attr listlist: A list of variables, usually ints or strings, separated by commas. optional A list of attributes you wish to return. Any attributes from a Nutritics Object are accepted. Your developer account must be cleared by Nutritics staff to retrieve cetrain attributes. &attr=vitc,vitd,quid
replaceID intint: A numeric value without a decimal or stringstring: Letters, numbers, or other types of characters optional ID or IFC of an existing object you would like to replace with your new data. &replaceID=U.5032
FOOD, RECIPE, LOG & MEALPLAN OBJECTS ONLY:
components list of arrayslist of arrays: A list of array objects, separated by commas, each containing multiple variables. optional A list of sub-objects for your new object. Usually food or recipe objects themselves, these elements make up your ingredients or log content. (See object components for available fields) &components=[id:U.123,quantity:45],[id:U.456,quantity:250ml]

Return Data

The new Nutritics Object with the default array of calculated values. To retrieve specific values, add the attr field to the request

Syntax

https://{username}:{pasword}@www.nutritics.com/api/v1.1/CREATE/{object}&{attribute1}={value1}&{attribute2}={value2}&etc...&components=[{component1}],[{component1}],etc..

Example Requests

Create a new client:

https://[USERNAME]:[PASSWORD]@www.nutritics.com/api/v1.1/CREATE/client&name=Joe&gender=m&dob=1990/01/01&weight=70&height=180

Create a new recipe:

https://[USERNAME]:[PASSWORD]@www.nutritics.com/api/v1.1/CREATE/recipe&name=Pizza Dough&components=[id:12345,quantity:60],[id:GB15.63832,quantity:496,name:4 cups of flour,cmethod:Baked or roasted],[id:GB15.65502,quantity:568,name:A pint of warm water]

Edit an existing Nutritics object

Parameters

field type required description example
{object} stringstring: Letters, numbers, or other types of characters required The name of any type of Nutritics object &recipe
id intint: A numeric value without a decimal or stringstring: Letters, numbers, or other types of characters required The ID or IFC of the object you wish to modify &recipe=123
{attributes} multiplemultiple: Multiple variables in the form &attribute=value required Add fields & values you wish to update (See Nutritics Objects for available attributes) &weight=60
attr listlist: A list of variables, usually ints or strings, separated by commas. optional A list of attributes you wish to return. Any attributes from a Nutritics Object are accepted. Your developer account must be cleared by Nutritics staff to retrieve cetrain attributes. &attr=vitc,vitd,quid
FOOD, RECIPE, LOG & MEALPLAN OBJECTS ONLY:
{subfunction} stringstring: Letters, numbers, or other types of characters optional Additional functions for managing components. Accepted values are below. &add=[foodID:123,name:Pinch of salt,quantity:3]
addAdd new components
updateUpdates existing components with new values
replaceUpdates existing components and automatically adds any missing components.
deleteRemoves the components listed
components list of arrayslist of arrays: A list of array objects, separated by commas, each containing multiple variables. optional Attach components to the add, update & replace subfunctions. (See object components for available fields) &replace=[id:45123,foodID:123,quantity:500],[id:45612,quantity:120]
{componentIDs} listlist: A list of variables, usually ints or strings, separated by commas. optional Only used for delete subfunction. Specify the IDs of the components you wish to delete. &delete=45123,45612

Return Data

Default (status and msg only)

Syntax

https://{username}:{pasword}@www.nutritics.com/api/v1.1/MODIFY/{object}={id}&{attribute1}={value1}&{attribute2}={value2}&etc...&{subfunction}=( {componentID} OR [{component1}],[{component2}],etc... )

Example Requests

Edit the weight of client 1005:

https://[USERNAME]:[PASSWORD]@www.nutritics.com/api/v1.1/MODIFY/client=1005&weight=70

Edit the quantity of two ingredients in recipe U.123:

https://[USERNAME]:[PASSWORD]@www.nutritics.com/api/v1.1/MODIFY/recipe=U.123&update=[id:12456,quantity:450ml],[id:34789,quantity:serving]

Delete an existing Nutritics object permanently, including all data associated with it. To delete individual object components, use MODIFY function.

Parameters

field type required description example
{object} stringstring: Letters, numbers, or other types of characters required The name of any type of Nutritics object &client=
id intint: A numeric value without a decimal or stringstring: Letters, numbers, or other types of characters required The ID or IFC of the object you wish to delete &client=U.123

Return Data

Default (status and msg only)

Syntax

https://[USERNAME]:[PASSWORD]@www.nutritics.com/api/v1.1/DELETE/{object}={id}

Example Request

https://[USERNAME]:[PASSWORD]@www.nutritics.com/api/v1.1/DELETE/client=123

The ADMIN function performs basic checks and updates on your developer account.

Return Data

Returns a simple array containing the information requested

Syntax

https://[USERNAME]:[PASSWORD]@www.nutritics.com/api/v1.1/ADMIN/{object}&{field}

Example Requests

Check the API status:

https://[USERNAME]:[PASSWORD]@www.nutritics.com/api/v1.1/ADMIN/api&status

Check your dev account status & limits:

https://[USERNAME]:[PASSWORD]@www.nutritics.com/api/v1.1/ADMIN/dev&status

Update your account settings:

https://[USERNAME]:[PASSWORD]@www.nutritics.com/api/v1.1/ADMIN/dev&password=abcdef https://[USERNAME]:[PASSWORD]@www.nutritics.com/api/v1.1/ADMIN/dev&defaultUserID=1234

Update your default database sources for LIST:

https://[USERNAME]:[PASSWORD]@www.nutritics.com/api/v1.1/ADMIN/dev&dbs=N,GB15,US15,IE09

The HELP function returns an array detailing all available attributes for any object. Authentication is not required for this function.

Return Data

Returns a simple array containing the information requested

Syntax

https://www.nutritics.com/api/v1.1/HELP/{object}&{field}

Example Requests

List all available attributes for Nutritics recipe objects:

https://www.nutritics.com/api/v1.1/HELP/recipe

List all available values for Nutritics food categories:

https://www.nutritics.com/api/v1.1/HELP/food&cats

List all available Nutritics databases:

https://www.nutritics.com/api/v1.1/HELP/food&srcs https://www.nutritics.com/api/v1.1/HELP/food&srcs&group=National Databases

Response Codes

Code Name Description
200 Success  Everything worked as expected.
400 Bad Request  The request was unacceptable, often due to missing a required parameter.
401 Unauthorized  Your username or password are incorrect 
402 Limit Reached  (check your account status)
403 Forbidden  Your account does not have permission to access the requested resource
404 Not Found  No object found under the specified filters.
429 Too Many Requests  Too many requests hit the API too quickly. We recommend an exponential backoff of your requests.
500, 502,
503, 504 
Server Errors  Something went wrong on our end  (check the API status)

 

Changelog v1.1

Features:

  • New columns available in every object. Read the documentation for more information
  • Search can now be made by IFC (removed src & code option)
  • Portion cost field added to the portion object
  • Cooking methods added to recipes
  • Response codes were updated to web standards
  • CREATE function now accepts the ID of an object to replace
  • MODIFY, ADMIN and HELP functions added
  • Added photos to LIST results
  • queryTime parameter added to all requests
  • Additional units accepted on component quantity (lb, kg, oz, ml, etc)
  • Additional options added to component quantity ("one serving" & "recipe total")
  • Dedicated barcodes added to portions
  • New API Documentation
  • New colour coding on explorer sample code & JSON response
  • Activity object is now supported

Fixes:

  • Removed id2 we recommend to use IFC instead
  • "ingredients" field renamed to "components"
  • "attr" field added to to LIST
  • "filter" field in DETAIL renamed to "attr"
  • "source" field renamed to "src"
  • "txt" field renamed to to "msg"
  • "measure" field removed. Use "quantity" instead.
  • Empty values will be shown as "" instead of "null"
  • Boolean values will be shown as true or false instead of "0","1"
  • Integer and float values will be shown without quotes
  • Fixed source field default value on recipe creation
  • Fixed output encoding problems
  • Fixed bug when deleting client
  • Fixed problem when filtering fields on foods and recipes
  • Fixed problem when showing allergens on foods and recipes
  • Fixed problems with traffic lights and labeling
  • Fixed bug when using pagination on foods and recipes
  • Fixed bug related when detail a food or recipe and adding specific nutrients in the filter
  • Javascript Callback for JSONP repaired