Recipes API

The Recipes API is designed to provide all the information you might need about Hain Celestial Group recipes.

Base URL : http://api.hcgweb.net/{version}/recipes/

The current version is v1.

Available Services:

recipeSelectors
recipeSearch
categoryDetail
recipeDetail

recipeSelectors

Returns lists of recipe categories and products for use in pulldown menus. The categories are those defined for the site and the products are those contained in the ingredient lists of the recipes. The category data lists each main category with it's subcategories. The product data is supplied in two forms: one sorted according to brand, and one that is a straight alphabetical listing of products.

URL Format

http://api.hcgweb.net/{version}/recipes/recipeSelectors/{api-key}/{format}/{site-id}

Request

The HTTP Method used is GET.

Parameter	Required	Description	`Options` and `Samples`
version	Yes	The version of the API that you are using.	`v1`
api-key	Yes	The unique api key provided by hcgWeb.	`45ghe8561frD`
format	Yes	The format you would like the data returned in.	`xml` `json`
site-id	Yes	The alpha code used to identify which HCG site you want data about.	`eb` = Earth's Best See a complete list of codes.

Example Requests

http://api.hcgweb.net/v1/recipes/recipeSelectors/45ghe8561frD/xml/hc

Response

Parameter	Description
source	An indicator of which database the data came from
response	The requested data
	recipe-categories	The categories and subcategories defined for this site.
	brands	The brands featured in the recipes with a product listing for each brand.
	products	Alphabetial listing of products.
status	An indicator of the success of the call

XML Schema

<recipeSelectors generator="hcg" version="1.0">
    <source>dev</source>
    <response>
        <recipe-categories>
            <recipe-category>
                <CategoryID>21</CategoryID>
                <CategoryCode>meal-type</CategoryCode>
                <CategoryName>Meal Type</CategoryName>
                <recipe-subcategories>
                    <recipe-subcategory>
                        <CategoryID>22</CategoryID>
                        <CategoryCode>breakfast</CategoryCode>
                        <CategoryName>Breakfast</CategoryName>
                        <CategoryDetailURL>http://api.hcgweb.net/...</CategoryDetailURL>
                    </recipe-subcategory>
                    <recipe-subcategory>...</recipe-subcategory>
                </recipe-subcategories>
            </recipe-category>
            <recipe-category>...</recipe-category>
        </recipe-categories>
        <brands>
            <brand>
                <BrandName>Arrowhead Mills</BrandName>
                <BrandCode>arrowhead-mills</BrandCode>
                <products>
                    <product>
                        <SiteID>am</SiteID>
                        <ProductID>247</ProductID>
                        <ProductCode>yellow-corn-meal</ProductCode>
                        <ProductName>Organic Yellow Corn Meal</ProductName>
                        <ProductDetailURL>http://api.hcgweb.net/...</ProductDetailURL>
                    </product>
                    <product>...</product>
                </products>
            </brand>
            <brand>...</brand>
        </brands>
        <products>
            <product>
                <BrandName>Arrowhead Mills</BrandName>
                <BrandCode>arrowhead-mills</BrandCode>
                <SiteID>am</SiteID>
                <ProductID>247</ProductID>
                <ProductCode>yellow-corn-meal</ProductCode>
                <ProductName>Organic Yellow Corn Meal</ProductName>
                <ProductDetailURL>http://api.hcgweb.net/...</ProductDetailURL>
            </product>
            <product>...</product>
        </products>
    </response>
    <status>success</status>
</recipeSelectors>

recipeSearch

Returns a list of search results. If the query parameter is blank, all recipes will be returned, filtered by any product and/or category parameters.

URL Format

http://api.hcgweb.net/{version}/recipes/recipeSearch

Request

The HTTP Method used is POST.

Parameter	Required	Description	`Options` and `Samples`
version	Yes	The version of the API that you are using.	`v1`
api-key	Yes	The unique api key provided by hcgWeb.	`45ghe8561frD`
format	Yes	The format you would like the data returned in.	`xml` `json`
site-id	Yes	The alpha code used to identify which HCG site you want data about.	`eb` = Earth's Best See a complete list of codes.
query	No	Recipe search query. Same as what you'd type into the search box.	`chicken soup` Default: empty string
product	No	A product ID if the search is to be limited to recipes containing that product.	`247` = Organic Yellow Corn Meal Default: empty string
category	No	An array of category IDs if the search is to be limited to recipes linked to the categories. These are added to the POST string in the form `category[]=22&category[]=45`.	`22` = Breakfast Default: empty array
limit	No	Max number of recipes to be returned.	`25` Default: 10
offset	No	Start the query at the specified cursor value. This is used for pagination.	`10` starts with the 11th search result. Default: 0

Example Requests

Response

Parameter	Description
source	An indicator of which database the data came from
response	The requested data
	count	Number of recipes in the result. If the query yields no results, the count will be 0.
	next_offset	Value that can be passed back to the API as offset to yield the next page of recipes for the same query. If the query yields no results, next_offset will be an empty string.
	total	The total number of recipes in the database matching the query.
	recipes	Recipe objects
status	An indicator of the success of the call

XML Schema

<recipeSearch generator="hcg" version="1.0">
    <source>dev</source>
    <response>
        <count></count>
        <next_offset></next_offset>
        <total></total>
        <recipes>
            <recipe>
                <RecipeID>12</RecipeID>
                <RecipeCode>veggie-meatballs</RecipeCode>
                <Title>Veggie Meatballs</Title>
                <Yield></Yield>
                <PrepTime></PrepTime>
                <CookTime></CookTime>
                <Description></Description>
                <Citation></Citation>
                <ImageFile></ImageFile>
                <ImageWidth></ImageWidth>
                <ImageHeight></ImageHeight>
                <Ingredients>
                    <Ingredient>
                        <Quantity></Quantity>
                        <Name></Name>
                        <ProductOneName></ProductOneName>
                        <ProductOneLink></ProductOneLink>
                        <ProductTwoName></ProductTwoName>
                        <ProductTwoLink></ProductTwoLink>
                        <IsHeading></IsHeading>
                    </Ingredient>
                    <Ingredient>...</Ingredient>
                </Ingredients>
                <Directions></Directions>
                <Featured>0</Featured>
                <FeaturedProducts>
                    <Product>
                        <ProductID></ProductID>
                        <ProductCode></ProductCode>
                        <ProductName></ProductName>
                        <UPC></UPC>
                        <ProductDetailURL>http://api.hcgweb.net/...</ProductDetailURL>
                    </Product>
                    <Product>...</Product>
                </FeaturedProducts>
            </recipe>
            <recipe>...</recipe>
        </recipes>
    </response>
    <status>success</status>
</recipeSearch>

categoryDetail

Returns a complete recipe category detail record for the specified recipe category.

URL Format

http://api.hcgweb.net/{version}/recipes/categoryDetail/{api-key}/{format}/{site-id}/{id-type}/{category-id}

Request

The HTTP Method used is GET.

Parameter	Required	Description	`Options` and `Samples`
version	Yes	The version of the API that you are using.	`v1`
api-key	Yes	The unique api key provided by hcgWeb.	`45ghe8561frD`
format	Yes	The format you would like the data returned in.	`xml` `json`
site-id	Yes	The alpha code used to identify which HCG site you want data about.	`eb` = Earth's Best See a complete list of codes.
id-type	Yes	The type of information being passed to identify the recipe.	`id` - the recipe category's record id number `code` - the alpha-numeric code based on the recipe category's name
category-id	Yes	The recipe category identifier according to the indicated id-type.	`291` = id `whole-grain-cereals` = code

Response

Parameter	Description
source	An indicator of which database the data came from
response	The requested data
response	recipe-category	Category object
status	An indicator of the success of the call

XML Schema

<categoryDetail generator="hcg" version="1.0">
    <source>dev</source>
    <response>
        <recipe-category>
            <CategoryID></CategoryID>
            <CategoryCode></CategoryCode>
            <CategoryName></CategoryName>
            <CategoryText></CategoryText>
            <ImageFile></ImageFile>
            <ImageWidth></ImageWidth>
            <ImageHeight></ImageHeight>
            <Language></Language>
            <MetaTitle></MetaTitle>
            <MetaDescription></MetaDescription>
            <MetaKeywords></MetaKeywords>
            <MetaAbstract></MetaAbstract>
            <MetaRobots></MetaRobots>
            <Status></Status>
        </recipe-category>
    </response>
    <status>success</status>
</categoryDetail>

recipeDetail

Returns a complete recipe detail record for the specified recipe and a list of categories that the recipe is assigned to. The category list is a shortened record with just the CategoryID and CategoryCode to be used to look up the full category record if needed.

URL Format

http://api.hcgweb.net/{version}/recipes/recipeDetail/{api-key}/{format}/{site-id}/{id-type}/{recipe-id}

Request

The HTTP Method used is GET.

Parameter	Required	Description	`Options` and `Samples`
version	Yes	The version of the API that you are using.	`v1`
api-key	Yes	The unique api key provided by hcgWeb.	`45ghe8561frD`
format	Yes	The format you would like the data returned in.	`xml` `json`
site-id	Yes	The alpha code used to identify which HCG site you want data about.	`eb` = Earth's Best See a complete list of codes.
id-type	Yes	The type of information being passed to identify the recipe.	`id` - the recipe's record id number `code` - the alpha-numeric code based on the recipe's name
recipe-id	Yes	The recipe identifier according to the indicated id-type.	`291` = id `whole-grain-rice-cereal` = code

Response

Parameter	Description
source	An indicator of which database the data came from
response	The requested data
	recipe	Recipe object
	recipe-categories	Simplified category object(s)
status	An indicator of the success of the call

XML Schema

<recipeDetail generator="hcg" version="1.0">
    <source>dev</source>
    <response>
        <recipe>
            <RecipeID>12</RecipeID>
            <RecipeCode>veggie-meatballs</RecipeCode>
            <Title>Veggie Meatballs</Title>
            <Yield></Yield>
            <PrepTime></PrepTime>
            <CookTime></CookTime>
            <Description></Description>
            <Citation></Citation>
            <ImageFile></ImageFile>
            <ImageWidth></ImageWidth>
            <ImageHeight></ImageHeight>
            <Ingredients>
                <Ingredient>
                    <Quantity></Quantity>
                    <Name></Name>
                    <ProductOneName></ProductOneName>
                    <ProductOneLink></ProductOneLink>
                    <ProductTwoName></ProductTwoName>
                    <ProductTwoLink></ProductTwoLink>
                    <IsHeading></IsHeading>
                </Ingredient>
                <Ingredient>...</Ingredient>
            </Ingredients>
            <Directions></Directions>
            <Featured>0</Featured>
            <FeaturedProducts>
                <Product>
                    <ProductID></ProductID>
                    <ProductCode></ProductCode>
                    <ProductName></ProductName>
                    <UPC></UPC>
                    <ProductDetailURL>http://api.hcgweb.net/...</ProductDetailURL>
                </Product>
                <Product>...</Product>
            </FeaturedProducts>
        </recipe>
        <recipe-categories>
            <recipe-category>
                <CategoryID></CategoryID>
                <CategoryCode></CategoryCode>
                <CategoryDetailURL>http://api.hcgweb.net/...</CategoryDetailURL>
            </recipe-category>
            <recipe-category>...</recipe-category>
        </recipe-categories>
    </response>
    <status>success</status>
</recipeDetail>

HCG Web Services Documentation 21 Oct 2011 • Version 1.0

Recipes API

Available Services:

recipeSelectors

URL Format

Request

Example Requests

Response

recipeSearch

URL Format

Request

Example Requests

Response

categoryDetail

URL Format

Request

Response

recipeDetail

URL Format

Request

Response

HCG Web Services Documentation
21 Oct 2011 • Version 1.0