HCG Web Services Documentation
21 Oct 2011 • Version 1.0

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

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

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
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>