iDreamBooks API

Introduction

iDreamBooks' API is intended for developers to access information about a certain title including its aggregated critic rating, critic review count and critic review snippets. iDreamBooks aggregates editorial reviews from professional critics like NYTimes and WashingtonPost to generate a highly authentic book rating.

Getting Started

Getting the Data

There are two ways to embed the rating and review data of a title on your site:

Widgets

You can embed all the critic reviews of a title by copying and pasting the following code in your website's HTML.

<div id="idb_iframe_container">
</div>


<script type="text/javascript">

  //REQUIRED INPUTS
    var isbn = {ISBN}; // Replace with ISBN / EISBN / ASIN of the book
    var api_key = {API_KEY}; //Replace with the developer key (Submit the form to get a key)

  //Optional Settings
    var smiley = 'true'; // Change to false if do not want to show smiley with each review
    var width = 700;     // Width of the reviews iframe
    var height = 400;    // Height of the reviews iframe

    // For some titles we only have "unrated" critic reviews.
    // Such reviews have not gone through a quality assurance step yet and don't have a 
    // positive or negative sentiment.
    // If you want to include the reviews of such titles change the following to 'true'
    var unrated = 'false';

  // DO NOT EDIT   
    (function() {
      var wf = document.createElement('script');
      var host = "idreambooks.com";  
      wf.src = ('https:' == document.location.protocol ? 'https' : 'http') +
          '://'+host+'/reviews_widget.js?api_key='+ api_key +'&isbn='+ isbn +
          '&smiley='+ smiley +'&width='+width + '&height=' + height;
      wf.type = 'text/javascript';
      wf.async = 'true';
      var s = document.getElementsByTagName('script')[0];
      s.parentNode.insertBefore(wf, s);
    })();

</script>
        

Two inputs are required: {API_KEY} is an alpha-numeric key that validates the request and {ISBN} is the 10 or 13 digit isbn or eisbn of the book. There are some optional parameters as well as explained in the above code snippet.

Widgets Example

Request code snippet

<div id="idb_iframe_container">
</div>


<script type="text/javascript">

  //REQUIRED INPUTS
    var isbn = "9781410439154";  //ISBN / EISBN / ASIN of the book
    var api_key = "example_key"; //Replace with the developer key (Submit the form to get a key)

  //Optional Settings
    var smiley = 'true'; // Change to false if do not want to show smiley with each review
    var width = 700;     // Width of the reviews iframe
    var height = 400;    // Height of the reviews iframe
    var unrated = 'false';

  // DO NOT EDIT   
    (function() {
      var wf = document.createElement('script');
      var host = "idreambooks.com";
      wf.src = ('https:' == document.location.protocol ? 'https' : 'http') +
          '://'+host+'/reviews_widget.js?api_key='+ api_key +'&isbn='+ isbn +
          '&smiley='+ smiley +'&width='+width + '&height=' + height;
      wf.type = 'text/javascript';
      wf.async = 'true';
      var s = document.getElementsByTagName('script')[0];
      s.parentNode.insertBefore(wf, s);
    })();

</script>
          

Response

The widget styling can be customized (requires Api Key)

JSON/XML

You can also perform a title search by sending a HTTP GET request to the following URI:

http://idreambooks.com/newbooks/api.xml?q={keywords}&key={yourAPIkey}

http://idreambooks.com/newbooks/api.json?q={keywords}&key={yourAPIkey}

{keywords} in the above URI is the search query. It can be any of the following:

{yourAPIkey} is an alpha-numeric key that validates the request. The key can be obtained by filling out the API Key Form.

JSON/XML Example

Request code snippet (click each request to see its response):

http://idreambooks.com/newbooks/api.xml?q=moonwalking+with+einstein+by+Foer&key=example_key

http://idreambooks.com/newbooks/api.xml?q=9781101475973&key=example_key

Understanding the JSON/XML Response

Data Format

The response is in XML or JSON (JavaScript Object Notation) format.

Key - Values

We return the information for a single title that matches the search query. The response has the title, author, rating overview and critic reviews for the book. Some of the information contained in the key-value pairs is explained below:

Note: A "rating" is not calculated if the "review-count" is less than 4. In such a case, all key-value pairs are returned except for "rating" and "to-read-or-not". For some books, that do not have critic reviews, we would provide "unrated" critic reviews. Unrated critic reviews are in the process of being rated and do not have a rating associated with them. They are yet to go through quality assurance. Some of the information contained in the key-value pairs returned in such a scenario is explained below:

Please fill out the form below to obtain an API key.

When using our API, you agree to the following Terms & Conditions:

• iDreamBooks' rating will always be displayed as a percentage. You can do so my adding the text “%” besides the rating. The rating will always be preceded or succeeded by the to-read-or-not icon. A smiley icon will be used if the rating is over 70% and a sad icon if it is less than 70%.
• Since iDreamBooks' rating is based on critic reviews, it will be a stand-alone rating and will not be lumped with ratings based on user reviews.
• Credit shall be given to iDreamBooks by either linking the rating and the icon to the relevant book page on iDreamBooks or by displaying and linking the following text besides the rating to the relevant book page on iDreamBooks: '{Title of book} reviews from idreambooks.com'.
• If you wish to display the snippets, they should be in a separate section than user reviews and should be labelled appropriately. A label to the effect of “Editorial Reviews” or “Book Reviews by Critics” or {Title of book} Reviews from iDreamBooks” should help distinguish between critics reviews & user reviews. Underneath the section of snippets you wish to display, credit shall be given to iDreamBooks by displaying and linking the following text to the relevant book page on iDreamBooks: '{Title of book} reviews from idreambooks.com'.
• Up to 5 snippets will be sent as part of the response. Depending on whether the snippet is positive or negative, a smiley or sad icon will be sent for a given snippet. When displaying the snippet, the relevant icon can be displayed too.
• You agree to not use the API to redistribute, harvest or index iDreamBooks' data without our explicit consent.
• You agree to not truncate, modify or change our data.
• You may not store our data except for caching purposes.
• You may not nofollow any of the required links, as mentioned above, to iDreamBooks' pages.
• iDreamBooks reserves the right to suspend your account for violation of the above terms. We also reserve the right to update or modify these terms without prior notice.