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
(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.
You must replace all 5 instances of GOODGUIDE_ID and all 2 instances of NAME for the script to work correctly.
<!-- 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('©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>
You must replace all 4 instances of GOODGUIDE_ID and 1 instance NAME for the script to work correctly.
<!-- 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('©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>
