Good Guide API Reference (Version 1.0)

Overview

The GoodGuide API enables developers to access GoodGuide.com data through a REST-based interface.  Version 1.0 of the GoodGuide API currently supports one operation, search, that returns information and GoodGuide ratings about entities.  An entity as defined by the GoodGuide API is a product, company, brand, or product category for which there is a GoodGuide rating.  Through the API, you can find information about any entity currently available on GoodGuide.com.

Request format

Calls to the GoodGuide API follow this basic format:

http://api.goodguide.com/search.xml?api_key=abc123&api_version=1.0&parameter1=X&;parameter2=Y...

Parameters

You must include parameters in your search request to describe what entities you would like returned.  The parameters are as follows:

api_key

Your unique developer api key.  You can request a key here.  This parameter is required.   We currently manually approve all API key requests, but we typically respond to requests within one day.

api_version

Currently, the only supported value for this parameter is 1.0.  This parameter is required.

q (Query)

To perform a keyword search, use "q=".  By default, a keyword query will return products only (e.g., a keyword query for "Acme Company" will return Acme Company's products).  See the entity_type  parameter for information on how to query for companies or other types of entities.

Example:

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

upc

You may search for products using a product's upc code.  The GoodGuide API attempts to find an exact match for the provided upc code; if no exact match is found, however, the API may return related products.  For example, if there is no exact match for the UPC you request, GoodGuide may return a list of products from the same company or brand.

Example:

http://api.goodguide.com/search.xml?api_key=abc123&api_version=1.0&upc=123456789012

id

If you know the GoodGuide id of a product, you may search for it directly using the id parameter.  The id parameter overrides most search parameters (q, upc, parent_ids, entity_type, limit, page, sort_by, and sort_order are ignored).

Example:

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

You can find the GoodGuide id for a product or company using its URL on GoodGuide.com.  For example, in the GoodGuide URL: http://www.goodguide.com/products/130442-burts-bees-baby-bee-buttermilk-lotion the GoodGuide id is 130442.

entity_type

By default, the GoodGuide API returns product results.  To search for other entity types, use the entity_type parameter.  Currently, the GoodGuide API supports the following entity types: product, brand, company, and category.

Example:

http://api.goodguide.com/search.xml?api_key=abc123&api_version=1.0&q=Acme+Company&entity_type=company

parent_ids[]

You may restrict a keyword or upc search to entities within a set of parents (such as finding all products within a particular company or category), designated by an array of GoodGuide ids.  The GoodGuide API uses an array notation to allow multiple parent_ids, which are logically AND-ed together.

Example:

http://api.goodguide.com/search.xml?api_key=abc123&api_version=1.0&parent_ids[]=123&parent_ids[]=456&q=shampoo

count

You can set the number of entities returned from a search request using the count parameter.  The default count is 20.  The maximum count is 50.

Example:

http://api.goodguide.com/search.xml?api_key=abc123&api_version=1.0&q=shampoo&count=30

page

To fetch additional pages of entities, use the page parameter.  By default, the first page of results is returned.

Example:

http://api.goodguide.com/search.xml?api_key=abc123&api_version=1.0&q=shampoo&count=30&page=2

sort_by

The GoodGuide API supports 3 types of sorting for entities:

  • best_match: for keyword searches, show results that best match the query first (best_match is the default)
  • rating: sort by the overall GoodGuide rating (by default, sort_by=rating returns entities in descending order of rating.  See the sort_order parameter)
  • name: sort alphabetically by entity name

Example:

http://api.goodguide.com/search.xml?api_key=abc123&api_version=1.0&q=shampoo&sort_by=rating

sort_order

To change the order by which entities are sorted, use the sort_order parameter.  There are two valid values for this parameter:

  • desc: sort descending (default for sort_by=rating and sort_by=best_match)
  • asc: sort ascending (default for sort_by=name)

Example:

http://api.goodguide.com/search.xml?api_key=abc123&api_version=1.0&q=shampoo&sort_by=rating&sort_order=asc

api_format

Currently, the GoodGuide API support three types of response formats, specified by the api_format paramater:

  • reference (default)
  • simple
  • badge

Each response format is described in detail In the next section.

Response Formats

All responses from the GoodGuide API have the following elements:

  • <goodguide-response>:  Every response is wrapped in a goodguide-response tag
  • <entities entity_type="X">: All search requests return one or more entities arrays.  An entity array consists of entity elements of a single type, designated by an "entity_type" attribute.
  • <entity entity_type="X">: An entity tag contains information about an entity.  It has an "entity_type" attribute designating its type.  An entity element may have different contents depending on the requested api_format.

reference

The reference format is the simplest response format.  It allows you to get a GoodGuide id for use in subsequent searches to get more detail.

  • <id>: The GoodGuide id of this entity
  • <name>: This entity's name

Example:

<goodguide-response>
  <entities entity_type="product">
    <entity entity_type="product">  
      <id>123</id>
      <name>Acme Company Bread, Whole Wheat</name>
    </entity>
  </entities>
</goodguide-response>

simple

To get GoodGuide ratings for entities, use the simple format.  This format has the following elements:

  • <id>: The GoodGuide id of this entity
  • <name>: This entity's name
  • <url>: A url on goodguide.com to find more information
  • <image-url>: A url for an image for this entity
  • <rating>: A rating has the following child elements
  •         <name>: The name of the rating (e.g., "Overall Performance")
  •         <value>: The 0-10 rating
  •         <sub-ratings>: A set of rating tags defining the constituent components of an overall rating (e.g., "Environmental Performance", "Health Performance", and "Social Performance").

 

Additionally, each entity type has specific fields.

Products

  • <parents>: an array of entities (in reference format) containing the parent entities for this product — its brand, company, and product category.  Some products may not have all types of parents.  Some products may have multiple types of each parent (e.g., a shampoo + conditioner product is in two categories); for these products, the API returns only one of the parents.
  • <upc>: a UPC code for this product

Example:

<goodguide-response>
  <entities entity_type="product">
    <entity entity_type="product">  
      <id>123</id>
      <name>Acme Company Bread, Whole Wheat</name>
      <url>http://www.goodguide.com/products/123-acme-company-bread-whole-wheat</url>
      <image-url>http://www.goodguide.com/images/123.png</image-url>
      <rating>                                                                                                                                                                                                                                   
        <name>Overall</name>                                                                                                                                                                                          
        <value>7.4</value>   
        <sub-ratings>
          <rating>
            <name>Environmental Performance</name>
            <value>9.2</value>
          </rating>
          <rating>
            <name>Health Performance</name>
            <value>5.8</value>
          </rating> 
          <rating>
            <name>Social Performance</name>
            <value>7.1</value>
          </rating>                                                                                                                                                                                         
        </sub-ratings>                                                                                                                                                                                                                                                                                                                                                                                                                                            
      </rating>
      <upc>123456789012</upc>
      <parents entity_type='category'>
        <entity entity_type="category">
          <id>968</id>
          <name>Bread</name>
        </entity>
        <entity entity_type="category">
          <id>207</id>
          <name>Whole Wheat Products</name>
        </entity>
      </parents>
      <parents entity_type='brand'>
        <entity entity_type="brand">
          <id>1067</id>
          <name>ACME</name>
        </entity>
      </parents>
    </entity>
  </entities>
</goodguide-response>

Brands

  • children: an array of entities (in reference format) containing the products for this brand.

Example:

<goodguide-response>
  <entities entity_type="brand">
    <entity entity_type="brand">  
      <id>789</id>
      <name>Acme Bread</name>
      <url>http://www.goodguide.com/brands/789-acme-bread</url>
      <image-url>http://www.goodguide.com/images/789.png</image-url>
      <rating>                                                                                                                                                                                                                                   
        <name>Overall</name>                                                                                                                                                                                          
        <value>9.0</value>   
        <sub-ratings>
          <rating>
            <name>Environmental Performance</name>
            <value>9.2</value>
          </rating>
          <rating>
            <name>Health Performance</name>
            <value>9.0</value>
          </rating> 
          <rating>
            <name>Social Performance</name>
            <value>8.8</value>
          </rating>                                                                                                                                                                                         
        </sub-ratings>                                                                                                                                                                                                                                                                                                                                                                                                                                            
      </rating>
      <children>
        <entity entity_type="product">
          <id>123</id>
          <name>Acme Company Bread, Whole Wheat</name>
        </entity>
        <entity entity_type="product">
          <id>124</id>
          <name>Acme Company Bread, White</name>
        </entity>
      </children>
    </entity>
  </entities>
</goodguide-response>

Companies

  • children: an array of entities (in reference format) containing the brands produced by this company.
<goodguide-response>
  <entities entity_type="company">
    <entity entity_type="company">  
      <id>912</id>
      <name>Acme Company</name>
      <url>http://www.goodguide.com/company/912-acme-company</url>
      <image-url>http://www.goodguide.com/images/921.png</image-url>
      <rating>                                                                                                                                                                                                                                   
        <name>Overall</name>                                                                                                                                                                                          
        <value>5.8</value>   
        <sub-ratings>
          <rating>
            <name>Environmental Performance</name>
            <value>5.1</value>
          </rating>
          <rating>
            <name>Social Performance</name>
            <value>6.5</value>
          </rating>                                                                                                                                                                                         
        </sub-ratings>                                                                                                                                                                                                                                                                                                                                                                                                                                            
      </rating>
      <children entity_type='brand'>
        <entity entity_type="brand">
          <id>789</id>
          <name>Acme Bread</name>
        </entity>
     </children>
    </entity>
  </entities>
</goodguide-response>

Categories

  • children: an array of entities (in reference format) containing the products in this category.

Example:

<goodguide-response>
  <entities entity_type="category">
    <entity entity_type="category">  
      <id>11</id>
      <name>Shampoo</name>
      <url>http://www.goodguide.com/categories/11-shampoo</url>
      <image-url>http://www.goodguide.com/images/11.png</image-url>
      <rating>                                                                                                                                                                                                                                   
        <name>Overall</name>                                                                                                                                                                                          
        <value>8.8</value>   
        <sub-ratings>
          <rating>
            <name>Environmental Performance</name>
            <value>9.5</value>
          </rating>
          <rating>
            <name>Health Performance</name>
            <value>8.1</value>
          </rating> 
          <rating>
            <name>Social Performance</name>
            <value>8.8</value>
          </rating>                                                                                                                                                                                         
       </sub-ratings>                                                                                                                                                                                                                                                                                                                                                                                                                                            
     </rating>
     <children entity_type='product'>
       <entity entity_type="product">
         <id>123</id>
         <name>Acme Shampoo</name>
      </entity>
      <entity entity_type="product">
        <id>234</id>
        <name>Beta Shampoo</name>
      </entity>
    </children>
  </entity>
 </entities>
</goodguide-response>

badge

  • <id>: The GoodGuide id of this entity
  • <name>: This entity's name
  • <large-badge-url>: a url linking to an embeddable image containing the entity's rating in a large format
  • <small-badge-url>: a url linking to a smaller image containing the entity's rating
  • <large-badge-html>: suggested html for embedding the large badge on a web page
  • <small-badge-html>: suggested html for embedding the small badge on a web page

Example:

<goodguide-response>
  <entities entity_type="product">
    <entity entity_type="product">  
      <id>123</id>
      <name>Acme Company Bread, Whole Wheat</name>
      <large-badge-url>http://www.goodguide.com/products/123/rating.png?size=large</large-badge-url>
      <small-badge-url>http://www.goodguide.com/products/123/rating.png?size=small</small-badge-url>
      <large-badge-html>[Suggested HTML for embedding the large badge]</large-badge-html>
      <small-badge-html>[Suggested HTML for embedding the small badge]</small-badge-html>
    </entity>
  </entities>
</goodguide-response>

version 30 as of 2 years ago by goodguide Admin

0 Comments

Please sign in to post a comment.