API Usage Examples

This document outlines some common use cases of the API.  Feel free to adapt these examples for your own uses.

GoodGuide Rating Badges

You can use our API to generate rating badges for use on your own website.  These badges show ratings for products, companies, and brands, and they come in two different sizes.  For example, the product rating for Burt's Bees Buttermilk Lotion is shown below:

Small Format

Large Format

GoodGuide Rating for Burt's Bees Baby Bee Buttermilk Lotion

 

You can access these badges for a given entity by adding the "format=badge" argument to any GoodGuide API query.  Alternately, you can use the templates below and fill in a GoodGuide ID manually if you only need to access the badges occasionally. (Once our API goes out of beta testing, we will provide links on GoodGuide.com to generate this embed code automatically—Thank you for your patience as we test our service.)

Note: When using the GoodGuide badge you must (a) place the badge on your page in a manner that clearly associates it with the specific brand, company, or product being rated, and (b) include a link back to GoodGuide.com.

 

Small Formate Template

Replace GOODGUIDE_ID with the ID of a product, company, or brand (which can be found in any GoodGuide.com URL like http://www.goodguide.com/products/130442-burts-bees-baby-bee-buttermilk-lotion (id 130442).  Replace NAME with the product, brand, or company name.  (If your are linking to a brand or a company, you must replace "/products" with "/brands" or "/companies" in the links to GoodGuide.com.

You must replace all 5 instances of GOODGUIDE_ID and all 2 instances of NAME for the script to work correctly. 

Note that, while this code will work in most web browsers without the <!-- IE6 Overrides --> section, the rating badges will have mis-colored backgrounds for users with Internet Explorer 6 if these are left out.

<!-- In accordance with the terms and conditions of GoodGuide's User Agreement (http://www.goodguide.com/about/user_agreement), the code for this badge must be copied and embedded in its entirety and may not be altered in any way -->
<script type="text/javascript"> var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www."); document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E")); </script>
<script type="text/javascript"> try { _uff = 0; var pageTrackerGoodGuide = _gat._getTracker("UA-7045112-3"); pageTrackerGoodGuide._initData(); function fireEvent() { pageTrackerGoodGuide._trackEvent('Badge Impression', "'" + document.location.host + "'", 'GOODGUIDE_ID'); } } catch(err) {} </script>
<div style="text-align: center; width: 160px; position: relative;" class="goodguide-rating">
<a style="text-decoration: none;" href="http://www.goodguide.com/products/GOODGUIDE_ID">
<!-- IE6 Overrides -->
<!--[if lte IE 6]>
<style type="text/css">
.goodguide-rating img { display: none; }
</style>
<div style="width: 157px; height: 65px; filter: progid:DXImageTransform.Microsoft.AlphaImageLoader(src='http://www.goodguide.com/products/GOODGUIDE_ID/rating.png?size=small',sizingMethod='crop');"></div>
<div style="position: absolute; top: 0; left: 0; width: 157px; height: 65px; cursor: pointer; z-index: 20; filter: alpha(opacity=0); background: black;"></div>
<![endif]-->
<img style="border: none;" src="http://www.goodguide.com/products/GOODGUIDE_ID/rating.png?size=small" alt="GoodGuide Rating for NAME" onload="fireEvent();" oncontextmenu="alert('&copy;2009 GoodGuide, Inc. All rights reserved by GoodGuide and its licensors and data providers.'); return false;" />
</a>
<div style="text-align: center; font-family: Helvetica, Arial; font-size: 11px; margin-top: 5px">
Product Rating for <a href="http://www.goodguide.com/products/GOODGUIDE_ID">NAME</a>
</div>
</div> 

 

Large Format Template

Replace GOODGUIDE_ID with the ID of a product, company, or brand (which can be found in any GoodGuide.com URL like http://www.goodguide.com/products/130442-burts-bees-baby-bee-buttermilk-lotion (id 130442).  Replace NAME with the product, brand, or company name.  (If your are linking to a brand or a company, you must replace "/products" with "/brands" or "/companies" in the links to GoodGuide.com.

You must replace all 4 instances of GOODGUIDE_ID and 1 instance NAME for the script to work correctly.

 

 Note that, while this code will work in most web browsers without the <!-- IE6 Overrides --> section, the rating badges will have mis-colored backgrounds for users with Internet Explorer 6 if these are left out.

<!-- In accordance with the terms and conditions of GoodGuide's User Agreement (http://www.goodguide.com/about/user_agreement), the code for this badge must be copied and embedded in its entirety and may not be altered in any way -->
<script type="text/javascript"> var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www."); document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E")); </script>
<script type="text/javascript"> try { _uff = 0; var pageTrackerGoodGuide = _gat._getTracker("UA-7045112-3"); pageTrackerGoodGuide._initData(); function fireEvent() { pageTrackerGoodGuide._trackEvent('Badge Impression', "'" + document.location.host + "'", 'GOODGUIDE_ID'); } } catch(err) {} </script>
<span class="goodguide-rating" style="position: relative;">
<a style="text-decoration: none;" href="http://www.goodguide.com/products/GOODGUIDE_ID">
<!-- IE6 Overrides -->
<!--[if lte IE 6]>
<style type="text/css">
.goodguide-rating img { display: none; }
</style>
<div style="width: 157px; height: 91px; filter: progid:DXImageTransform.Microsoft.AlphaImageLoader(src='http://www.goodguide.com/products/GOODGUIDE_ID/rating.png?size=large',sizingMethod='crop');"></div>
<div style="position: absolute; top: 0; left: 0; width: 157px; height: 91px; cursor: pointer; z-index: 20; filter: alpha(opacity=0); background: black;"></div>
<![endif]-->
<img style="border: none;" src="http://www.goodguide.com/products/GOODGUIDE_ID/rating.png?size=large" alt="GoodGuide Rating for NAME" onload="fireEvent();" oncontextmenu="alert('&copy;2009 GoodGuide, Inc. All rights reserved by GoodGuide and its licensors and data providers.'); return false;" />
</a>
</span>

Search and Lookup

The most basic use of the API is to do a free-text (or UPC) search and then pick a result to view in detail.  For example, a user may search for Burt's Bees Shampoo and then pick a specific product to view ratings for that product.  This can be done with two API calls.

First, lookup the results for your seach query:

http://api.goodguide.com/search.xml?api_key=abc123&api_version=1.0&q=Burt's+Bees+Shampoo

Response (You can also look up multiple pages of results by adding a page=N parameter):

<goodguide-response>
    <entities type="product">
        <entity type="product">
            <id>178421</id>
            <name>Burt's Bees Herbal Treatment Shampoo</name>
        </entity>
        <entity type="product">
            <id>178424</id>
            <name>Burt's Bees Rosemary Mint Shampoo Bar</name>
        </entity>
        ...
        <entity type="product">
            <id>130448</id>
            <name>Burt's Bees Baby Bee Shampoo Bar</name>
        </entity>
    </entities>
</goodguide-response>

Then, lookup specific information for Burt's Bees Baby Bee Shampoo Bar (id 130448):

http://api.goodguide.com/search.xml?api_key=abc123&api_version=1.0&api_format=simple&id=130448

Response:

<goodguide-response>
    <entities type="product">
        <entity entity_type="product">
            <id>130448</id>
            <name>Burt's Bees Baby Bee Shampoo Bar</name>
            <url>
                http://www.goodguide.com/products/130448-burts-bees-baby-bee-shampoo-bar
            </url>
            <rating>
                <name>root</name>
                <value>7.9</value>
                <sub-ratings>
                    <rating>
                        <name>social</name>
                        <value>8.5</value>
                    </rating>
                    <rating>
                        <name>environmental</name>
                        <value>7.7</value>
                    </rating>
                    <rating>
                        <name>health-and-safety</name>
                        <value>7.6</value>
                    </rating>
                </sub-ratings>
            </rating>
            <parents entity_type="brand">
                <entity entity_type="brand">
                    <id>122097</id>
                    <name>Burt's Bees</name>
                </entity>
            </parents>
            <parents entity_type="company">
                <entity entity_type="company">
                    <id>159278</id>
                    <name>Burt's Bees, Inc.</name>
                </entity>
            </parents>
            <parents entity_type="category">
                <entity entity_type="category">
                    <id>152655</id>
                    <name>Baby Shampoo</name>
                </entity>
            </parents>
        </entity>
    </entities>
</goodguide-response>

Browsing by Category (Coming Soon)

It is also possible to browse products by looking up all products in a particular category.  You can search for categories (like Shampoo):

http://api.goodguide.com/search.xml?api_key=abc123&api_version=1.0&q=Shampoo&entity_type=category

Response:

<goodguide-response>
    <entities entity_type="category">
        <entity entity_type="category">
            <id>152655</id>
            <name>Baby Shampoo</name>
        </entity>
        <entity entity_type="category">
            <id>152725</id>
            <name>Lice Treatment Shampoo</name>
        </entity>
        <entity entity_type="category">
            <id>152758</id>
            <name>Shampoo</name>
        </entity>
    </entities>
</goodguide-response>

You can then use the parent_id[] parameter in order to find products in the Shampoo category (id 152758):

http://api.goodguide.com/search.xml?api_key=abc123&api_version=1.0&parent_ids[]=152758

Response:

<goodguide-response>
    <entities entity_type="product">
        <entity entity_type="product">
            <id>126394</id>
            <name>AHAVA Men's Mineral Shampoo</name>
        </entity>
        <entity entity_type="product">
            <id>126409</id>
            <name>AHAVA Mineral Shampoo</name>
        </entity>
        <entity entity_type="product">
            <id>126888</id>
            <name>Amplify Volumizing Shampoo</name>
        </entity>
        ...
        <entity entity_type="product">
            <id>132999</id>
            <name>Cristophe Beverly Hills Hydrating Shampoo</name>
        </entity>
    </entities>
</goodguide-response>