HCG Web Services Documentation
6 July 2009 • Version 1.0

Stores API

The Stores API is designed to provide access to the Hain Celestial Group's store locator databases.

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

The current version is v1.

The HTTP Methods used are GET and POST.

Note: The GET method is not really used in the sense that you do not write a query statement with key/value pairs. The values are separated by slashes, and all required values must be present in the order indicated.

Available Services:

storeProductList

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

http://api.hcgweb.net/{version}/stores/storeProductList/{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. 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 Links

Data Dictionary

The structure of the data is

storeProductList
{
   source
   response
   {
      ProductCategories
      [
         (ProductCategory -- may be multiple records)
         {
            CategoryID
            CategoryName
            Products
            [
               (Product -- may be multiple records)
               {
                  ProductNum
                  ProductName
               }
            ]
         }
      ],
      Products 
      [
         (Products -- may be multiple records)
         {
            ProductNum
            ProductName
         }
      ]
   },
   status
}

storeLocator

Returns a list of stores that may carry the specified within the specified zip code and radius. This service depends on user input. Form validation should be done at the client level to ensure that all required information is supplied.

The information supplied should be everything you need to list the stores in a single combined list or separated according to how accurate the information is. In addition, you should be able to supply Map and Message links. The GoogleMapKey is supplied if the domain from which the request came from is one where we maintain the key.

The data may be submitted via either the GET or POST method.

URL Format

Via GET:

http://api.hcgweb.net/{version}/stores/storeLocator/{api-key}/{format}/{site-id}/{product-num}/{zip}/{radius}/{count}/{sort}

Via POST:

http://api.hcgweb.net/{version}/stores/storeLocator

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.
product-num Yes The product that the user is searching for. This number is the 11-digit UPC with an extra 0 in front of it per the standards used by Nielsen. 002392320003
zip Yes The zip code where the user lives. 80301
radius No The distance in miles the user is willing to travel. 5
Default: 10
count No The number of results to return. 25
Default: 50
sort No The column on which the list should be sorted. Distance
Name
Default: Distance

Example Links

Data Dictionary

The structure of the data is

storeLocator
{
   source
   response
   {
      Search
      {
         <search fields>
      },
      Stores
      [
         (Store -- may be multiple records)
         {
            <store fields>
         }
      ]
   },
   status
}

The search and store fields are defined in an Excel spreadsheet:

storeMessage

Allows the user to submit information about any store and product so we can improve our databases. This service depends on user input. Form validation should be done at the client level to ensure that all required information is supplied.

The service cleans and saves the data to the database. It then returns the data in its response so you can do whatever post processing you might want to do such as sending out a verification email.

The data can be submitted via either the GET or POST method, but it is likely that you will want to use the POST method.

URL Format

Via GET:

http://api.hcgweb.net/{version}/stores/storeMessage/{api-key}/{format}/{site-id}/{StoreID}/{StoreName}/{Address1}/{Address2}/{City}/{State}/{Zip}/{Phone}/{ProductNum}/{ProductName}/{FirstName}/{LastName}/{Email}/{Affiliated}/{Message}/{Mode}

Via POST:

http://api.hcgweb.net/{version}/stores/storeMessage

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.
StoreID Yes The StoreID as supplied by the StoreLocator service. 196
StoreName Yes The StoreName as supplied by the StoreLocator service. RED BARN NATURAL GROCERY
Address1 Yes The Address1 as supplied by the StoreLocator service. 357 VAN BUREN ST
Address2 Yes The Address2 as supplied by the StoreLocator service. 4th and Blair
City Yes The City as supplied by the StoreLocator service. EUGENE
State Yes The State as supplied by the StoreLocator service. OR
Zip Yes The Zip as supplied by the StoreLocator service. 97402
Phone Yes The Phone as supplied by the StoreLocator service. 541-342-7503
ProductNum Yes The ProductNum as supplied by the StoreLocator service. 002392320003
ProductName Yes The ProductName as supplied by the StoreLocator service. First Sweet Potatoes
FirstName Yes The user's first name, input from a form. Jim
LastName Yes The user's last name, input from a form. Applegate
Email Yes The user's email address, input from a form. fake@domain.com
Affiliated Yes A 1 or 0 indicating whether the user is the owner or an employee of the store, input from a form. 0
Message Yes The user's message, input from a form. This store is closed.
Mode No A switch to put the service into test mode which will not save the data to the database. test
Default: active

Example Links

Data Dictionary

The structure of the data is

storeMessage
{
   response
   {
      Submitted
      {
         Message ID
         SiteID
         BrandName
         StoreID
         StoreName
         Address1
         Address2
         City
         State
         Zip
         Phone
         ProductNum
         ProductName
         FirstName
         LastName
         Email
         Affiliated
         Message
      }
   },
   status
}