Searching with the Genesis API

You can see the details on each of the search endpoints by following the links below:

How do you search for only user added foods?

Within a Search request, you can use the DataSourceFilter property and specify only "UserFoods".

Sample Request

request={"SearchText":"chicken", "StartIndex":1, "PageSize":3, "FilterByPublicationStates":["Published"], "DataSourceFilter":["UserFoods"], "FilterByFoodTypes":["Recipe"]}

How do you search for only Ingredients/Recipes?

Within a Search request, you can use the FilterByFoodTypes property and specify only "Ingredients" or "Recipes". This applies to all of the Search endpoints:

Sample Request

request={"SearchText":"salt", "StartIndex":1, "PageSize":3, "FilterByPublicationStates":["Published"], "DataSourceFilter":["UserFoods"], "FilterByFoodTypes":["Ingredient"]}

What is a PublicationState?

There are currently 3 different publication states: Draft, Published, and Archived. Currently only Draft and Published are supported via the API. A food has a Published publication state if it is a member of a published group. All other foods are treated as having a Draft state.

You can learn about publishing a Group in Genesis R&D Food here.

Nutrients and Units

I'm not seeing any units associated with my nutrient values. How do I know what unit these nutrient values are in?

For each given nutrient in the Genesis database, there is only one unit associated with it. For example, Protein's unit is always Grams. To look up what unit is associated with a specific nutrient, use the ListNutrients endpoint.

Getting Analyses via the Genesis API

What is the difference between the GetFoodByFoodId, GetFoodByUserCode and GetAnalysis endpoints?

GetFoodByFoodId and GetFoodByUserCode will give you the basic metadata for the Ingredient or Recipe you are looking for. If the Food returned is an Ingredient, both GetFood... endpoints will include the nutrient profile. If the Food returned is a Recipe, both GetFood... endpoints will include all its component items. See the prior links for sample responses returned for Ingredients and Recipes.

GetAnalysis will return a complete set of nutritional analyses for a Food at a specified amount. If the Food is a Recipe, it will include analyses for each of its Food Items as well. See the prior link for sample responses returned for Ingredients and Recipes.

How do I get label rounded values for a food?

Use the GetAnalysis endpoint. The response will contain a "Labels" section, which will contain various properties for the Label object associated with the Recipe you queried for. Within the "Labels" section is a collection titled "Nutrients" which contains the Nutrients displayed on the Label format chosen for the Recipe.

Only Recipes will have Label rounded nutrient values since Ingredients do not have labels.

Labels Section of GetAnalysis Response

"Labels": [
        {
            "ServingSizeWeight": {
                "en-US": "100g",
                "es-MX": "100g",
                "fr-CA": "100g"
            },
            "ServingSizeText": null,
            "ServingSizeCombined": {
                "en-US": "Serving size (100g)",
                "es-MX": "Serving size (100g)",
                "fr-CA": "Serving size (100g)"
            },
            "ServingsPerContainer": null,
            "Nutrients": [
                {
                    "NutrientId": "84a8709a-0000-0000-ebf9-90cea7d9d44f",
                    "AnalysisIdSpecified": false,
                    "DisplayValue": "100",
                    "RoundedValue": {
                        "Quantity": {
                            "Value": "100",
                            "Type": 14
                        },
                        "UnitId": "00000000-0000-0000-0000-000000000000"
                    },
                    "RawValue": {
                        "Quantity": {
                            "Value": "100",
                            "Type": 14
                        },
                        "UnitId": "00000000-0000-0000-0000-000000000000"
                    },
                    "DailyValuesSpecified": false,
                    "IdSpecified": false
                },
                {
                    "NutrientId": "84a8709a-0011-0000-ebf9-90cea7d9d44f",
                    "AnalysisIdSpecified": false,
                    "DisplayValue": "5",
                    "RoundedValue": {
                        "Quantity": {
                            "Value": "5",
                            "Type": 14
                        },
                        "UnitId": "a7df0af5-0008-0000-7484-751e8eaf05c6"
                    },
                    "RawValue": {
                        "Quantity": {
                            "Value": "5",
                            "Type": 14
                        },
                        "UnitId": "a7df0af5-0008-0000-7484-751e8eaf05c6"
                    },
                    "DailyValues": [
                        {
                            "Authority": {
                                "Name": null,
                                "Iso3166Alpha2": null,
                                "Iso3166Alpha3": null,
                                "Iso3166NumericSpecified": false,
                                "Id": "bbf4846d-8400-43bb-944d-6021fda98225",
                                "IdSpecified": true
                            },
                            "RecommendationProfileId": "9e5fc62a-0fe6-11e1-bb3f-b8ac6fac0ca7",
                            "DisplayValue": "6",
                            "Percentage": 6
                        }
                    ],
                    "DailyValuesSpecified": true,
                    "IdSpecified": false
                },
                {
                    "NutrientId": "84a8709a-003c-0000-ebf9-90cea7d9d44f",
                    "AnalysisIdSpecified": false,
                    "DisplayValue": "20",
                    "RoundedValue": {
                        "Quantity": {
                            "Value": "20",
                            "Type": 14
                        },
                        "UnitId": "a7df0af5-0010-0000-7484-751e8eaf05c6"
                    },
                    "RawValue": {
                        "Quantity": {
                            "Value": "20",
                            "Type": 14
                        },
                        "UnitId": "a7df0af5-0010-0000-7484-751e8eaf05c6"
                    },
                    "DailyValues": [
                        {
                            "Authority": {
                                "Name": null,
                                "Iso3166Alpha2": null,
                                "Iso3166Alpha3": null,
                                "Iso3166NumericSpecified": false,
                                "Id": "bbf4846d-8400-43bb-944d-6021fda98225",
                                "IdSpecified": true
                            },
                            "RecommendationProfileId": "9e5fc62a-0fe6-11e1-bb3f-b8ac6fac0ca7",
                            "DisplayValue": "1",
                            "Percentage": 1
                        }
                    ],
                    "DailyValuesSpecified": true,
                    "IdSpecified": false
                },
                {
                    "NutrientId": "84a8709a-0081-0000-ebf9-90cea7d9d44f",
                    "AnalysisIdSpecified": false,
                    "DisplayValue": "--",
                    "RoundedValue": {
                        "Quantity": {
                            "Value": "-1",
                            "Type": 14
                        },
                        "UnitId": "00000000-0000-0000-0000-000000000000"
                    },
                    "RawValue": {
                        "Quantity": {
                            "Value": "418.4",
                            "Type": 14
                        },
                        "UnitId": "00000000-0000-0000-0000-000000000000"
                    },
                    "DailyValuesSpecified": false,
                    "IdSpecified": false
                },
                {
                    "NutrientId": "84a8709a-00d0-0000-ebf9-90cea7d9d44f",
                    "AnalysisIdSpecified": false,
                    "DisplayValue": "7",
                    "RoundedValue": {
                        "Quantity": {
                            "Value": "7",
                            "Type": 14
                        },
                        "UnitId": "a7df0af5-0008-0000-7484-751e8eaf05c6"
                    },
                    "RawValue": {
                        "Quantity": {
                            "Value": "7",
                            "Type": 14
                        },
                        "UnitId": "a7df0af5-0008-0000-7484-751e8eaf05c6"
                    },
                    "DailyValues": [
                        {
                            "Authority": {
                                "Name": null,
                                "Iso3166Alpha2": null,
                                "Iso3166Alpha3": null,
                                "Iso3166NumericSpecified": false,
                                "Id": "bbf4846d-8400-43bb-944d-6021fda98225",
                                "IdSpecified": true
                            },
                            "RecommendationProfileId": "9e5fc62a-0fe6-11e1-bb3f-b8ac6fac0ca7",
                            "DisplayValue": "25",
                            "Percentage": 25
                        }
                    ],
                    "DailyValuesSpecified": true,
                    "IdSpecified": false
                },
                {
                    "NutrientId": "84a8709a-03e8-0000-ebf9-90cea7d9d44f",
                    "AnalysisIdSpecified": false,
                    "DisplayValue": "--",
                    "RoundedValue": {
                        "Quantity": {
                            "Value": "-1",
                            "Type": 14
                        },
                        "UnitId": "00000000-0000-0000-0000-000000000000"
                    },
                    "RawValue": {
                        "Quantity": {
                            "Value": "0.75",
                            "Type": 14
                        },
                        "UnitId": "00000000-0000-0000-0000-000000000000"
                    },
                    "DailyValuesSpecified": false,
                    "IdSpecified": false
                },
                {
                    "NutrientId": "84a8709a-03e9-0000-ebf9-90cea7d9d44f",
                    "AnalysisIdSpecified": false,
                    "DisplayValue": "--",
                    "RoundedValue": {
                        "Quantity": {
                            "Value": "-1",
                            "Type": 14
                        },
                        "UnitId": "a7df0af5-0008-0000-7484-751e8eaf05c6"
                    },
                    "RawValue": {
                        "Quantity": {
                            "Value": "100",
                            "Type": 14
                        },
                        "UnitId": "a7df0af5-0008-0000-7484-751e8eaf05c6"
                    },
                    "DailyValuesSpecified": false,
                    "IdSpecified": false
                },
                {
                    "NutrientId": "84a8709a-03ec-0000-ebf9-90cea7d9d44f",
                    "AnalysisIdSpecified": false,
                    "DisplayValue": "45",
                    "RoundedValue": {
                        "Quantity": {
                            "Value": "45",
                            "Type": 14
                        },
                        "UnitId": "00000000-0000-0000-0000-000000000000"
                    },
                    "RawValue": {
                        "Quantity": {
                            "Value": "45",
                            "Type": 14
                        },
                        "UnitId": "00000000-0000-0000-0000-000000000000"
                    },
                    "DailyValuesSpecified": false,
                    "IdSpecified": false
                }
            ],

Many of my Requests succeed, but calls to GetAnalysis and the GetFood endpoints (GetFoodByFoodId or GetFoodByUserCode) result in 404 (Not Found).

While there may be a few scenarios that result in this, a possible cause is a discrepancy in the installed versions of Genesis and the API. As a starting point, refer to the Genesis API Compatibility Chart. With each update to Genesis itself, there will be a corresponding update to the API that also needs be installed.

Creating and Editing Foods via the Genesis API

There are two endpoints available for creating and editing Foods:

Both NewFood and UpdateFood use a "RecipeEdit" section in their requests. When creating a Food with the NewFood endpoint, omit the "Id" field. When editing a Food with the UpdateFood endpoint, you must include the "Id" field, populated with the Id of the Recipe you wish to edit, in the Recipe section. The following examples include the "Id" field to show its typical location for UpdateFood requests.

There is a ListFoods endpoint that will list every Food in the database and its corresponding guid Id, unless various filter properties are applied to the request. It is an inefficient way to find the Food ids you are interested in. Typically, Food ids are obtained using one of the Search methods, or by using GetFoodByUserCode.

The ellipsis ("...") implies parts of the request where additional fields or sections could be included. See each endpoint's documentation link for what a complete request would look like.

How do I add a food to a Group in the FoodEditService?

Add the the Group id to the Groups collection in the Recipe section of the request:

Add Food to Group

request={
	"RecipeEdits":[{
		"Recipe":{
			"Id":"<FOOD_ID_GUID>",
			...
		     "GroupsIds":[
    		     "021c021f-000a-0000-8d69-0b60293379ea"
	    	 ],
		    ...
		},
	}]
	...
}

You can get the guid associated with each Group via the ListGroups endpoint. All Food Groups in the response will have a GroupType of 70.

How do I subscribe a food to an Allergen in the FoodEditService?

Add an AllergenStatement to the AllergenStatement collection on the Food, and specify the Allergen id in the AllergenGroups collection.

Add Allergen to Food

request={
	"RecipeEdits":[{
		"Recipe":{
			"Id":"<FOOD_ID_GUID>",
			...
		     "AllergenStatements":[{
        		 "AllergenGroupIds":[
		             "7d52c4c5-e396-4e8c-ae8e-ca5dd9ddc307",
        		 ]
		     }],
			...
		},
	}]
	...
}

You can get the guid associated with each Allergen via the ListAllergens endpoint. Allergens are treated under the hood as Groups, which is why they are obtained this way. All Allergens in the response will have a GroupType of 65.

How do I set a measure on a food in the FoodEditService?

Add a Conversion to the Conversions collection on the Food, specifying a "From" Amount and a "To" Amount.

In this example, we a creating a volume measure for a Recipe, setting 50 ml (UnitId of "a7df0af5-000b-0000-7484-751e8eaf05c6") = 100 g (UnitId of "a7df0af5-0008-0000-7484-751e8eaf05c6")

Add a Measure to a Food

request={
	"RecipeEdits":[{
		"Recipe":{
			"Id":"<FOOD_ID_GUID>",
			...
		    "Conversions": [
            {
                "From": {
                    "Quantity": {
                        "Value": "50",
                        "Type": 14
                    },
                    "UnitId": "a7df0af5-000b-0000-7484-751e8eaf05c6"
                },
                "ConversionFactor": {
                    "Value": "1",
                    "Type": 14
                },
                "To": {
                    "Quantity": {
                        "Value": "100",
                        "Type": 14
                    },
                    "UnitId": "a7df0af5-0008-0000-7484-751e8eaf05c6"
                }
            }],
			...
		},
	}]
	...
}

How do I set the Product/Supplier on a food in the FoodEditService?

Product and Supplier can be specified in the Brand property on a Food. If the given Product/Supplier don't exist in the Genesis database, they will be added.

Set Product and Supplier on a Food

request={
	"RecipeEdits":[{
		"Recipe":{
			"Id":"<FOOD_ID_GUID>",
			...
		    "Brand":{
		        "Supplier":"Supplier X",
		        "Product":"Product X"
		     },
			...
		},
	}]
	...
}

You can get the guid associated with each Unit (for setting the UnitId field above) via the ListUnits endpoint.

How do I set nutrient values on an Ingredient in the FoodEditService?

Nutrients for an ingredient are set in a nutrient profile. You can associate an ingredient with a nutrient profile by using the NutrientProfileId field on the Ingredient, and the Id field on a NutrientProfile.

How do I set the cost of a food in the FoodEditService?

Use the AmountCost property located on the food.

Cost is always set as a Cost per Amount. In the example below, the request sets Cost to be to $5.00 per 100 Grams.

Set the Cost for a Food

request={
	"RecipeEdits":[{
		"Recipe":{
			"Id":"<FOOD_ID_GUID>",
			...
		     "AmountCost":{
        		 "Amount":{
		             "Quantity":{
        		         "Type":"Double",
                		 "Value":100
		             },
        		     "UnitId":"a7df0af5-0008-0000-7484-751e8eaf05c6"
		         },
        		 "Cost":"5"
		     },
			...
		},
	}]
	...
}

You can get the guid associated with each Unit (for setting the UnitId field above) via the ListUnits endpoint.

How do I add Ingredients to my Recipe in the FoodEditService?

Add the FoodItem(s), using their corresponding FoodId(s), and the Quantity of each Ingredient in the Recipe, to the Recipes' Items collection.

Add Ingredients to a Recipe

request={
	"RecipeEdits":[{
		"Recipe":{
			"Id":"<FOOD_ID_GUID>",
			...
		     "Items":[{
		         "FoodId":"<FOOD_ITEM_ID_GUID>",
        		 "Amount":{
		             "Quantity":{
        		         "Value":"100","Type":"Double"
		             },
        		     "UnitId":"a7df0af5-0008-0000-7484-751e8eaf05c6"}
		     }]
			...
		},
	}]
	...
}

You can get the guid associated with each Unit (for setting the UnitId field above) via the ListUnits endpoint.

Can I set nutrient value overrides on Recipes in the FoodEditService?

Nutrient value overrides are not currently supported in the FoodEditService.

Getting a Label Image via the Genesis API

Why am I getting a null response in the LabelImageService?

There could be various reasons why a null response is received, but the most common cases are

The food you are querying is not Published NOTE: This restriction is being removed in 4.0 release
The food you are querying is not a Recipe or Advanced Label

What is the format of the Image being returned in the LabelImageService?

Images returned in the LabelImageService will always be PNG's.

Miscellaneous Questions

How do I check which version of Genesis API I have installed?

Go to %Program Files (x86)%\Esha Research\GenesisAPI\bin
Right-click on the GenesisApi.dll and select the Details tab from the dialog that pops up

When making a request, I am met with 'Error: read ECONNRESET'. What might cause that?

A probable cause of this problem is an invalid Unit (UnitId). For example, if your Request calls for a volume amount of an ingredient - but there is no volume measure defined in Genesis, this error will occur. Please verify the available measures from within Genesis itself (edit the record in question, and look to the 'Measures' or 'Yields/Measures' page. Alternatively, attempt to add the ingredient/recipe to another Recipe in the amount & measure within the request.

I get an error when making a request that has special characters (e.g. &). How do I handle that?

Instead of using html code, you should be able to use the URL encoding characters for a character such as ampersand (&). As reference:

https://www.w3schools.com/tags/ref_urlencode.ASP

As an example, I have a User Code as "ABC & 123". A request of the following should result that item:

Sample Request

request={"UserCode": "ABC %26 123"}

I am able to successfully get a response when testing the API on the installed server. However, when making a request from a client/local machine, I get a 500 Internal Service Error with "Message": "The 'SQLNCLI11' provider is not registered on the local machine."

Install Microsoft® SQL Server® 2012 Native Client on the client/local machine and test. It should return a 200 response code successfully.

What do the values for FoodType in a Response represent?

FoodType 82 is always a RecipeDto.
FoodType 73 is always an IngredientDto.

I have enabled Audit Trails for Genesis, but my updates through the API are not showing in the Audit history.

If the Audit Trail feature was recently enabled, there may be need to restart the IIS service for the API to adopt the change.

Open Internet Information Services (IIS) Manager in Windows
Select the GenesisAPI site
At the right under Manage Website, click Restart

In addition to the above, for applicable Request calls, make sure to include the EditDetails section as illustrated in the example requests of this documentation. For example:

        "EditDetails":{
            "EditMessage":"Creating New Ingredient",
            "EditCaller":{
                "Name":"Our PLM System"
            }
        }

Browser not supported