documentation/manual/en/module_specs/Zend_Gdata_Books.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="zend.gdata.books">
   4     <title>Using the Book Search Data API</title>
   5
   6     <para>
   7         The Google Book Search Data <acronym>API</acronym> allows client applications to view
   8         and update Book Search content in the form of Google Data <acronym>API</acronym> feeds.
   9     </para>
  10
  11     <para>
  12         Your client application can use the Book Search Data <acronym>API</acronym> to issue
  13         full-text searches for books and to retrieve standard book information,
  14         ratings, and reviews. You can also access individual users'
  15         <ulink url="http://books.google.com/googlebooks/mylibrary/">library collections and
  16             public reviews</ulink>. Finally, your application can submit authenticated requests
  17         to enable users to create and modify library collections, ratings, labels,
  18         reviews, and other account-specific entities.
  19     </para>
  20
  21     <para>
  22         For more information on the Book Search Data <acronym>API</acronym>, please refer to the
  23         official <ulink url="http://code.google.com/apis/books/gdata/developers_guide_php.html">PHP
  24             Developer's Guide</ulink> on code.google.com.
  25     </para>
  26
  27     <sect2 id="zend.gdata.books.authentication">
  28         <title>Authenticating to the Book Search service</title>
  29
  30         <para>
  31             You can access both public and private feeds using the Book Search
  32             Data <acronym>API</acronym>. Public feeds don't require any authentication, but they are
  33             read-only. If you want to modify user libraries, submit reviews or
  34             ratings, or add labels, then your client needs to authenticate before
  35             requesting private feeds. It can authenticate using either of two
  36             approaches: AuthSub proxy authentication or ClientLogin username/password
  37             authentication. Please refer to the <ulink
  38                 url="http://code.google.com/apis/books/gdata/developers_guide_php.html#Authentication">Authentication
  39                 section in the <acronym>PHP</acronym> Developer's Guide</ulink> for more detail.
  40         </para>
  41     </sect2>
  42
  43     <sect2 id="zend.gdata.books.searching_for_books">
  44         <title>Searching for books</title>
  45
  46         <para>
  47             The Book Search Data <acronym>API</acronym> provides a number of feeds that list
  48             collections of books.
  49         </para>
  50
  51         <para>
  52             The most common action is to retrieve a list of books that match a
  53             search query. To do so you create a <code>VolumeQuery</code> object
  54             and pass it to the <code>Books::getVolumeFeed</code> method.
  55         </para>
  56
  57         <para>
  58             For example, to perform a keyword query, with a filter on
  59             viewability to restrict the results to partial or full view books, use
  60             the <code>setMinViewability</code> and <code>setQuery</code> methods
  61             of the <code>VolumeQuery</code> object. The following code snippet prints
  62             the title and viewability of all volumes whose metadata or text matches
  63             the query term "domino":
  64         </para>
  65
  66         <programlisting language="php"><![CDATA[
  67 $books = new Zend_Gdata_Books();
  68 $query = $books->newVolumeQuery();
  69
  70 $query->setQuery('domino');
  71 $query->setMinViewability('partial_view');
  72
  73 $feed = $books->getVolumeFeed($query);
  74
  75 foreach ($feed as $entry) {
  76     echo $entry->getVolumeId();
  77     echo $entry->getTitle();
  78     echo $entry->getViewability();
  79 }
  80 ]]></programlisting>
  81
  82         <para>
  83             The <code>Query</code> class, and subclasses like
  84             <code>VolumeQuery</code>, are responsible for constructing feed
  85             <acronym>URL</acronym>s. The VolumeQuery shown above constructs a <acronym>URL</acronym>
  86             equivalent to the following:
  87         </para>
  88
  89         <programlisting language="php"><![CDATA[
  90 http://www.google.com/books/feeds/volumes?q=keyword&amp;min-viewability=partial
  91 ]]></programlisting>
  92
  93         <para>
  94             Note: Since Book Search results are
  95             public, you can issue a Book Search query without authentication.
  96         </para>
  97
  98         <para>
  99             Here are some of the most common <code>VolumeQuery</code>
 100             methods for setting search parameters:
 101         </para>
 102
 103         <para>
 104             <code>setQuery:</code> Specifies a search
 105             query term. Book Search searches all book metadata and full text for
 106             books matching the term. Book metadata includes titles, keywords,
 107             descriptions, author names, and subjects.
 108             Note that any spaces, quotes or other punctuation in the parameter
 109             value must be <acronym>URL</acronym>-escaped. (Use a plus (<code>+</code>) for a space.)
 110             To search for an exact phrase, enclose the phrase in quotation marks.
 111             For example, to search for books matching the phrase "spy plane", set
 112             the <code>q</code> parameter to <code>%22spy+plane%22</code>.
 113             You can also use any of the <ulink url="http://books.google.com/advanced_book_search">
 114             advanced search operators</ulink> supported by Book Search. For example,
 115             <code>jane+austen+-inauthor:austen</code> returns matches that mention
 116             (but are not authored by) Jane Austen.
 117         </para>
 118
 119         <para>
 120             <code>setStartIndex:</code> Specifies
 121             the index of the first matching result that should be included in the
 122             result set. This parameter uses a one-based index, meaning the first
 123             result is 1, the second result is 2 and so forth. This parameter works
 124             in conjunction with the max-results
 125             parameter to determine which results to return. For example, to
 126             request the third set of 10 results—results 21-30—set
 127             the <code>start-index</code> parameter to <code>21</code> and the
 128             max-results parameter to <code>10</code>.
 129             Note: This isn't a general cursoring
 130             mechanism. If you first send a query with
 131             <code>?start-index=1&amp;max-results=10</code> and then send another
 132             query with <code>?start-index=11&amp;max-results=10</code>, the
 133             service cannot guarantee that the results are equivalent to
 134             <code>?start-index=1&amp;max-results=20</code>, because insertions and
 135             deletions could have taken place in between the two queries.
 136         </para>
 137
 138         <para>
 139             <code>setMaxResults:</code>
 140             Specifies the maximum number of results that should be included
 141             in the result set. This parameter works in conjunction with the
 142             start-index parameter to determine which
 143             results to return. The default value of this parameter is
 144             <code>10</code> and the maximum value is <code>20</code>.
 145         </para>
 146
 147         <para>
 148             <code>setMinViewability:</code> Allows you to filter the results according to the books'
 149             <ulink
 150                 url="http://code.google.com/apis/books/docs/dynamic-links.html#terminology">viewability
 151                 status</ulink>. This parameter accepts one of three values: <code>'none'</code>
 152             (the default, returning all matching books regardless of
 153             viewability), <code>'partial_view'</code> (returning only books
 154             that the user can preview or view in their entirety), or
 155             <code>'full_view'</code> (returning only books that the user can
 156             view in their entirety).
 157         </para>
 158
 159         <sect3 id="zend.gdata.books.partner_restrict">
 160             <title>Partner Co-Branded Search</title>
 161
 162             <para>
 163                 Google Book Search provides <ulink
 164                     url="http://books.google.com/support/partner/bin/answer.py?hl=en&amp;answer=65113">Co-Branded
 165                     Search</ulink>, which lets content partners provide full-text search of
 166                 their books from their own websites.
 167             </para>
 168
 169             <para>
 170                 If you are a partner who wants to do Co-Branded Search using the
 171                 Book Search Data <acronym>API</acronym>, you may do so by modifying the feed
 172                 <acronym>URL</acronym> above to point to your Co-Branded Search implementation. if,
 173                 for example, a Co-Branded Search is available at the following
 174                 <acronym>URL</acronym>:
 175             </para>
 176
 177             <programlisting language="php"><![CDATA[
 178 http://www.google.com/books/p/PARTNER_COBRAND_ID?q=ball
 179 ]]></programlisting>
 180
 181             <para>
 182                 then you can obtain the same results using the Book Search Data
 183                 <acronym>API</acronym> at the following <acronym>URL</acronym>:
 184             </para>
 185
 186             <programlisting language="php"><![CDATA[
 187 http://www.google.com/books/feeds/p/PARTNER_COBRAND_ID/volumes?q=ball+-soccer
 188 ]]></programlisting>
 189
 190             <para>
 191                 To specify an alternate <acronym>URL</acronym> when querying a volume feed, you can
 192                 provide an extra parameter to <code>newVolumeQuery</code>
 193             </para>
 194
 195             <programlisting language="php"><![CDATA[
 196 $query =
 197     $books->newVolumeQuery('http://www.google.com/books/p/PARTNER_COBRAND_ID');
 198 ]]></programlisting>
 199
 200             <para>
 201                 For additional information or support, visit our
 202                 <ulink url="http://books.google.com/support/partner/">Partner help center</ulink>.
 203             </para>
 204         </sect3>
 205     </sect2>
 206
 207     <sect2 id="zend.gdata.books.community_features">
 208         <title>Using community features</title>
 209
 210         <sect3 id="zend.gdata.books.adding_ratings">
 211             <title>Adding a rating</title>
 212
 213             <para>
 214                 A user can add a rating to a book. Book Search uses a 1-5
 215                 rating system in which 1 is the lowest rating. Users cannot
 216                 update or delete ratings.
 217             </para>
 218
 219             <para>
 220                 To add a rating, add a <code>Rating</code> object to a
 221                 <code>VolumeEntry</code> and post it to the annotation feed.
 222                 In the example below, we start from an empty <code>VolumeEntry</code> object.
 223             </para>
 224
 225             <programlisting language="php"><![CDATA[
 226 $entry = new Zend_Gdata_Books_VolumeEntry();
 227 $entry->setId(new Zend_Gdata_App_Extension_Id(VOLUME_ID));
 228 $entry->setRating(new Zend_Gdata_Extension_Rating(3, 1, 5, 1));
 229 $books->insertVolume($entry, Zend_Gdata_Books::MY_ANNOTATION_FEED_URI);
 230 ]]></programlisting>
 231         </sect3>
 232
 233         <sect3 id="zend.gdata.books.reviews">
 234             <title>Reviews</title>
 235
 236             <para>
 237                 In addition to ratings, authenticated users can submit reviews or
 238                 edit their reviews. For information on how to request previously
 239                 submitted reviews, see <ulink
 240                     url="#zend.gdata.books.retrieving_annotations">Retrieving annotations</ulink>.
 241             </para>
 242
 243             <sect4 id="zend.gdata.books.adding_review">
 244                 <title>Adding a review</title>
 245
 246                 <para>
 247                     To add a review, add a <code>Review</code> object to a
 248                     <code>VolumeEntry</code> and post it to the annotation
 249                     feed. In the example below, we start from an existing
 250                     <code>VolumeEntry</code> object.
 251                 </para>
 252
 253                 <programlisting language="php"><![CDATA[
 254 $annotationUrl = $entry->getAnnotationLink()->href;
 255 $review        = new Zend_Gdata_Books_Extension_Review();
 256
 257 $review->setText("This book is amazing!");
 258 $entry->setReview($review);
 259 $books->insertVolume($entry, $annotationUrl);
 260 ]]></programlisting>
 261             </sect4>
 262
 263             <sect4 id="zend.gdata.books.editing_review">
 264                 <title>Editing a review</title>
 265
 266                 <para>
 267                     To update an existing review, first you retrieve the
 268                     review you want to update, then you modify it, and
 269                     then you submit it to the annotation feed.
 270                 </para>
 271
 272                 <programlisting language="php"><![CDATA[
 273 $entryUrl = $entry->getId()->getText();
 274 $review   = new Zend_Gdata_Books_Extension_Review();
 275
 276 $review->setText("This book is actually not that good!");
 277 $entry->setReview($review);
 278 $books->updateVolume($entry, $entryUrl);
 279 ]]></programlisting>
 280             </sect4>
 281         </sect3>
 282
 283         <sect3 id="zend.gdata.books.labels">
 284             <title>Labels</title>
 285
 286             <para>
 287                 You can use the Book Search Data <acronym>API</acronym> to label volumes with
 288                 keywords. A user can submit, retrieve and modify labels. See
 289                 <ulink url="#zend.gdata.books.retrieving_annotations">Retrieving
 290                     annotations</ulink> for how to read previously submitted labels.
 291             </para>
 292
 293             <sect4 id="zend.gdata.books.submitting_labels">
 294                 <title>Submitting a set of labels</title>
 295
 296                 <para>
 297                     To submit labels, add a <code>Category</code> object
 298                     with the scheme <constant>LABELS_SCHEME</constant> to a
 299                     <code>VolumeEntry</code> and post it to the annotation feed.
 300                 </para>
 301
 302                 <programlisting language="php"><![CDATA[
 303 $annotationUrl = $entry->getAnnotationLink()->href;
 304 $category      = new Zend_Gdata_App_Extension_Category(
 305     'rated',
 306     'http://schemas.google.com/books/2008/labels');
 307 $entry->setCategory(array($category));
 308 $books->insertVolume($entry, Zend_Gdata_Books::MY_ANNOTATION_FEED_URI);
 309 ]]></programlisting>
 310             </sect4>
 311         </sect3>
 312
 313         <sect3 id="zend.gdata.books.retrieving_annotations">
 314             <title>Retrieving annotations: reviews, ratings, and labels</title>
 315
 316             <para>
 317                 You can use the Book Search Data <acronym>API</acronym> to retrieve annotations
 318                 submitted by a given user. Annotations include reviews, ratings, and
 319                 labels. To retrieve any user's annotations, you can send an
 320                 unauthenticated request that includes the user's user ID. To retrieve the
 321                 authenticated user's annotations, use the value <code>me</code> as the user ID.
 322             </para>
 323
 324             <programlisting language="php"><![CDATA[
 325 $feed = $books->getVolumeFeed(
 326             'http://www.google.com/books/feeds/users/USER_ID/volumes');
 327 <i>(or)</i>
 328 $feed = $books->getUserAnnotationFeed();
 329
 330 // print title(s) and rating value
 331 foreach ($feed as $entry) {
 332     foreach ($feed->getTitles() as $title) {
 333         echo $title;
 334     }
 335     if ($entry->getRating()) {
 336         echo 'Rating: ' . $entry->getRating()->getAverage();
 337     }
 338 }
 339 ]]></programlisting>
 340
 341             <para>
 342                 For a list of the supported query parameters, see the
 343                 <ulink url="#zend.gdata.books.query_parameters">query parameters</ulink>
 344                 section.
 345             </para>
 346         </sect3>
 347
 348         <sect3 id="zend.gdata.books.deleting_annotations">
 349             <title>Deleting Annotations</title>
 350
 351             <para>
 352                 If you retrieved an annotation entry containing ratings,
 353                 reviews, and/or labels, you can remove all annotations
 354                 by calling <code>deleteVolume</code> on that entry.
 355             </para>
 356
 357             <programlisting language="php"><![CDATA[
 358 $books->deleteVolume($entry);
 359 ]]></programlisting>
 360         </sect3>
 361     </sect2>
 362
 363     <sect2 id="zend.gdata.books.sharing_with_my_library">
 364         <title>Book collections and My Library</title>
 365
 366         <para>
 367             Google Book Search provides a number of user-specific
 368             book collections, each of which has its own feed.
 369         </para>
 370
 371         <para>
 372             The most important collection is the user's My Library, which
 373             represents the books the user would like to remember, organize, and
 374             share with others. This is the collection the user sees when accessing
 375             his or her <ulink url="http://books.google.com/books?op=library">My Library
 376                 page</ulink>.
 377         </para>
 378
 379         <sect3 id="zend.gdata.books.retrieving_books_in_library">
 380             <title>Retrieving books in a user's library</title>
 381
 382             <para>
 383                 The following sections describe how to retrieve a list
 384                 of books from a user's library, with or without query
 385                 parameters.
 386             </para>
 387
 388             <para>
 389                 You can query a Book Search public feed without authentication.
 390             </para>
 391
 392             <sect4 id="zend.gdata.books.retrieving_all_books_in_library">
 393                 <title>Retrieving all books in a user's library</title>
 394
 395                 <para>
 396                     To retrieve the user's books, send a query to the
 397                     My Library feed. To get the library of the authenticated
 398                     user, use <code>me</code> in place of <constant>USER_ID</constant>.
 399                 </para>
 400
 401                 <programlisting language="php"><![CDATA[
 402 $feed = $books->getUserLibraryFeed();
 403 ]]></programlisting>
 404
 405                 <para>
 406                     Note: The feed may not contain all of the user's books, because
 407                     there's a default limit on the number of results returned. For
 408                     more information, see the <code>max-results</code> query parameter in
 409                     <ulink url="#zend.gdata.books.searching_for_books">Searching for books</ulink>.
 410                 </para>
 411             </sect4>
 412
 413             <sect4 id="zend.gdata.books.retrieving_books_in_library_with_query">
 414                 <title>Searching for books in a user's library</title>
 415
 416                 <para>
 417                     Just as you can <ulink
 418                         url="#zend.gdata.books.searching_for_books">search across all books</ulink>,
 419                     you can do a full-text search over just the books in a
 420                     user's library. To do this, just set the appropriate
 421                     paramters on the <code>VolumeQuery</code> object.
 422                 </para>
 423
 424                 <para>
 425                     For example, the following query returns all the books in
 426                     your library that contain the word "bear":
 427                 </para>
 428
 429                 <programlisting language="php"><![CDATA[
 430 $query = $books->newVolumeQuery(
 431     'http://www.google.com/books/feeds/users' .
 432     '/USER_ID/collections/library/volumes');
 433 $query->setQuery('bear');
 434 $feed = $books->getVolumeFeed($query);
 435 ]]></programlisting>
 436
 437                 <para>
 438                     For a list of the supported query parameters, see the
 439                     <ulink url="#zend.gdata.books.query_pParameters">query parameters</ulink>
 440                     section. In addition, you can search for books that have been
 441                     <ulink url="#zend.gdata.books.labels">labeled by the user</ulink>:
 442                 </para>
 443
 444                 <programlisting language="php"><![CDATA[
 445 $query = $books->newVolumeQuery(
 446     'http://www.google.com/books/feeds/users/' .
 447     'USER_ID/collections/library/volumes');
 448 $query->setCategory(
 449 $query->setCategory('favorites');
 450 $feed = $books->getVolumeFeed($query);
 451 ]]></programlisting>
 452             </sect4>
 453         </sect3>
 454
 455         <sect3 id="zend.gdata.books.updating_library">
 456             <title>Updating books in a user's library</title>
 457
 458             <para>
 459                 You can use the Book Search Data <acronym>API</acronym> to add a book to, or remove
 460                 a book from, a user's library. Ratings, reviews, and labels are valid
 461                 across all the collections of a user, and are thus edited using the
 462                 annotation feed (see <ulink
 463                     url="#zend.gdata.books.community_features">Using community features</ulink>).
 464             </para>
 465
 466             <sect4 id="zend.gdata.books.library_book_add">
 467                 <title>Adding a book to a library</title>
 468
 469                 <para>
 470                     After authenticating, you can add books to the current user's library.
 471                 </para>
 472
 473                 <para>
 474                     You can either create an entry from scratch if you
 475                     know the volume ID, or insert an entry read from any feed.
 476                 </para>
 477
 478                 <para>
 479                     The following example creates a new entry and adds it to the library:
 480                 </para>
 481
 482                 <programlisting language="php"><![CDATA[
 483 $entry = new Zend_Gdata_Books_VolumeEntry();
 484 $entry->setId(new Zend_Gdata_App_Extension_Id(VOLUME_ID));
 485 $books->insertVolume(
 486     $entry,
 487     Zend_Gdata_Books::MY_LIBRARY_FEED_URI
 488 );
 489 ]]></programlisting>
 490
 491                 <para>
 492                     The following example adds an existing
 493                     <code>VolumeEntry</code> object to the library:
 494                 </para>
 495
 496                 <programlisting language="php"><![CDATA[
 497 $books->insertVolume(
 498     $entry,
 499     Zend_Gdata_Books::MY_LIBRARY_FEED_URI
 500 );
 501 ]]></programlisting>
 502             </sect4>
 503
 504             <sect4 id="zend.gdata.books.library_book_remove">
 505                 <title>Removing a book from a library</title>
 506
 507                 <para>
 508                     To remove a book from a user's library, call
 509                     <code>deleteVolume</code> on the <code>VolumeEntry</code> object.
 510                 </para>
 511
 512                 <programlisting language="php"><![CDATA[
 513 $books->deleteVolume($entry);
 514 ]]></programlisting>
 515             </sect4>
 516         </sect3>
 517     </sect2>
 518 </sect1>