HCG Web Services Documentation
6 July 2009 • Version 1.0

Products API

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

Base URL : {version}/products/

The current version is v1.

The HTTP Method used is GET.

Available Services:

productDetail

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

URL Format

{version}/products/productDetail/{api-key}/{format}/{site-id}/{id-type}/{product-id}

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.
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 product. id - the product's record id number
code - the alpha-numeric code based on the product's name
upc - the 11-digit UPC
product-id Yes The product identifier according to the indicated id-type. 291 = id
whole-grain-rice-cereal = code
02392390001 = upc

Example Links

Data Dictionary

The basic structure of the data is

productDetail
{
   source
   response
   {
      Product
      {
         <product fields>
      }
      ProductCategories
      [
         (ProductCategory -- may have multiple records)
         {
            <a shortened category record with just ID and Code>
         }
      ]
   },
   status
}

The product fields are defined in an Excel spreadsheet:

productNLEA

Returns a complete Nutrition Facts record for the specified product.

URL Format

{version}/products/productNLEA/{api-key}/{format}/{site-id}/{id-type}/{product-id}

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.
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 product. id - the product's record id number
code - the alpha-numeric code based on the product's name
upc - the 11-digit UPC
product-id Yes The product identifier according to the indicated id-type. 291 = id
whole-grain-rice-cereal = code
02392390001 = upc

Example Links

Data Dictionary

The basic structure of the data is

productNLEA
{
   source
   response
   {
      NLEA
      {
         <nlea fields>
      }
   },
   status
}

The nlea fields are defined in an Excel spreadsheet. The NLEA description is incomplete in that not every field has a description, but the fields follow a pattern that I think you will be able to figure out pretty easily.

productList

Returns the category detail for the specified category and a list of product detail records for all products assigned to the specified product category. If no category is specified, the category record is empty and all active products for the site are returned.

URL Format

{version}/products/productList/{api-key}/{format}/{site-id}/{id-type}/{category-id}

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.
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 No The type of information being passed to identify the category. id - the category's record id number
code - the alpha-numeric code based on the category's name
category-id No The product identifier according to the indicated id-type. 68 = id
baby-cereals = code

Example Links

Data Dictionary

The basic structure of the data is

productList
{
   source
   response
   {
      ProductCategory (optional, if category is specified)
      {
         <category fields>
      }
      Products
      [
         (Product -- may be multiple records)
         {
            <product fields>
         }
      ]
   },
   status
}

The category fields and product fields are defined in Excel spreadsheets:

productSimpleList

Returns a list of Products for the specified site for use in a pulldown menu. The data is supplied in two forms, one with categories so the list can be separated into categories, and one that is a straight alphabetical listing of products.

URL Format

{version}/products/productSimpleList/{api-key}/{format}/{site-id}/{use-groups}

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.
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.
use-groups No Whether to use the product groups. If you use groups, then a product with multiple sizes will be listed just once. Otherwise, all sizes of a product are listed with the product size as part of the product name. yes - use groups
no - do not use groups
Default: no

Example Links

Data Dictionary

The basic structure of the data is

productSimpleList
{
   source
   response
   {
      ProductCategories
      [
         (ProductCategory -- may be multiple records)
         {
            CategoryID
            CategoryName
            Products
            [
               (Product -- may be multiple records)
               {
                  ProductName
                  ProductCode
                  ProductID
                  UPC
                  CategoryID
               }
            ]
         }
      ],
      Products 
      [
         (Products -- may be multiple records)
         {
            ProductName
            ProductCode
            ProductID
            UPC
         }
      ]
   },
   status
}

The category fields and product fields are defined in Excel spreadsheets:

categoryDetail

Returns a complete Product Category record for the specified category.

URL Format

{version}/products/productList/{api-key}/{format}/{site-id}/{id-type}/{category-id}

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.
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 category. id - the category's record id number
code - the alpha-numeric code based on the category's name
category-id Yes The product identifier according to the indicated id-type. 68 = id
baby-cereals = code

Example Links

Data Dictionary

The basic structure of the data is

categoryDetail
{
   source
   response
   {
      ProductCategory
      {
         <category fields>
      }
   },
   status
}

The category fields are defined in an Excel spreadsheet:

categoryList

Returns a list of category detail records for all categories assigned to the specified site. The list of categories contains information that allows you to build a hierarchical tree from the data. The first record is the root node and can be ignored in most cases.

URL Format

{version}/products/categoryList/{api-key}/{format}/{site-id}

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

Data Dictionary

The basic structure of the data is

categoryList
{
   source
   response
   {
      ProductCategories
      [
         (ProductCategory -- may be multiple records)
         {
            <category fields>
         }
      ]
   },
   status
}

The category fields are defined in an Excel spreadsheet: