The Bookshare website has a new look!Learn what’s new and what’s coming
Donate
Bookshare home

API V1.0 Search and Browse

Notice: The Bookshare API V1 will be sunset on June 30, 2024 and will no longer be available. Partners will need to migrate to API V2 to continue accessing the Bookshare collection after that date. Learn about API V2.

Summary of Book Requests

URIDetailsResponse
api.bookshare.org/book/isbn/TextISBN LookupBook Metadata Response
api.bookshare.org/book/id/NumberBook Id LookupBook Metadata Response
api.bookshare.org/book/searchFTS/TextFull Text SearchBook List Response
api.bookshare.org/book/search/title/TextTitle SearchBook List Response
api.bookshare.org/book/search/author/TextAuthor SearchBook List Response
api.bookshare.org/book/search/TextTitle/Author SearchBook List Response
api.bookshare.org/book/search/since/DateDate Published SearchBook List Response
api.bookshare.org/book/latestLatest books added to BookshareBook List Response
api.bookshare.org/book/popularPopular books on BookshareBook List Response
api.bookshare.org/reference/category/listCategory ListCategory List Response
api.bookshare.org/book/search/category/TextCategory SearchBook List Response
api.bookshare.org/reference/grade/listGrade ListGrade List Response
api.bookshare.org/book/search/grade/TextGrade SearchBook List Response

Combining Multiple Search Criteria

You can combine multiple search criteria, such as category, grade, title, author and full text search The results set is the intersection of the criteria (i.e. AND operator). Note title and author cannot be combined together.  Here are some examples:

  • api.bookshare.org/book/search/grade/Fourth+grade/category/History *
  • api.bookshare.org/book/search/algebra/grade/Fourth+grade *
  • api.bookshare.org/book/search/grade/Fourth+grade/category/History/for/EMAIL_OF_END_USER **
  • api.bookshare.org/book/search/algebra/grade/Fourth+grade/for/EMAIL_OF_END_USER **

Summary of Newspaper / Magazine Requests

URIDetailsResponse
api.bookshare.org/periodical/id/NumberPeriodical Edition SearchPeriodical List Response
api.bookshare.org/periodical/id/Number/edition/Date/revision/NumberPeriodical Edition LookupEdition Metadata Response
api.bookshare.org/periodical/listPeriodical List SearchPeriodical List Response

Detail for Book and Periodical Requests

ISBN Lookup

  • Description: Look up a specific book by ISBN. Wildcard searches are not permitted. Either 13 or 10 digit ISBNs are accepted. Dashes are optional.
  • Format: api.bookshare.org/book/isbn/Text
  • Authentication: Generally Available
  • Response: Book Metadata Response
  • Example:
    • api.bookshare.org/book/isbn/026219502X
  • Errors:
    • Error 0 – Book not found

Book Id Lookup

  • Description: Look up a specific book by Bookshare Id. The id is part of the Book List Response
  • Format: api.bookshare.org/book/id/Number
  • Authentication: Generally Available
  • Response: Book Metadata Response
  • Example:
    • api.bookshare.org/book/id/12242
  • Errors:
    • Error 0 – Book not found

Full Text Search

  • Description: Search for books based on the supplied text matching author, title or content in the book.  Note that our search engine defaults to phonetic matching, so you may get results that differ in spelling from your search terms.  To prevent the use of phonetic matching or word stemming (e.g. cars matches car), enclose your search term in URL encoded quotes (%22).
  • Format: api.bookshare.org/book/searchFTS/Text
  • Authentication: Generally Available OR User Authenticated
  • Response: Book List Response
  • Examples:
    • api.bookshare.org/book/searchFTS/King   *
    • api.bookshare.org/book/searchFTS/Steven/limit/50   *
    • api.bookshare.org/book/searchFTS/Steven/page/2   *
    • api.bookshare.org/book/searchFTS/Steven/page/2/for/EMAIL_OF_END_USER **
  • Errors:
    • Error 10 – Invalid search character

Title Search

  • Description: Search for books based on the supplied text matching the title.   Note that our search engine defaults to phonetic matching, so you may get results that differ in spelling from your search terms.  To prevent the use of phonetic matching or word stemming (e.g. cars matches car), enclose your search term in URL encoded quotes (%22).
  • Format: api.bookshare.org/book/search/title/Text
  • Authentication: Generally Available OR User Authenticated
  • Response: Book List Response
  • Examples:
    • api.bookshare.org/book/search/title/Dark  *
    • api.bookshare.org/book/search/title/Dark%20Half  *
    • api.bookshare.org/book/search/title/Dark/for/EMAIL_OF_END_USER **
  • Errors:
    • Error 10 – Invalid search character

Author Search

  • Description: Search for books based on the supplied text matching the author.   Note that our search engine defaults to phonetic matching, so you may get results that differ in spelling from your search terms.  To prevent the use of phonetic matching or word stemming (e.g. cars matches car), enclose your search term in URL encoded quotes (%22).
  • Format: api.bookshare.org/book/search/author/Text
  • Authentication: Generally Available OR User Authenticated
  • Response: Book List Response
  • Example:
    • api.bookshare.org/book/search/author/Steven *
    • api.bookshare.org/book/search/author/Steven/for/EMAIL_OF_END_USER **
  • Errors:
    • Error 10 – Invalid search character

Title/Author Search

  • Description: Search for books based on the supplied text matching the title or author.   Note that our search engine defaults to phonetic matching, so you may get results that differ in spelling from your search terms.  To prevent the use of phonetic matching or word stemming (e.g. cars matches car), enclose your search term in URL encoded quotes (%22).
  • Format: api.bookshare.org/book/search/Text
  • Authentication: Generally Available OR User Authenticated
  • Response: Book List Response
  • Example:
    • api.bookshare.org/book/search/Steven *
    • api.bookshare.org/book/search/Steven/for/EMAIL_OF_END_USER **
  • Errors:
    • Error 10 – Invalid search character

Date Published Search

  • Description: Search for books that have been published live on Bookshare on or since the given date.
  • Format: api.bookshare.org/book/search/since/Date (MMDDYYYY format)
  • Authentication: Generally Available OR User Authenticated
  • Response: Book List Response
  • Example:
    • api.bookshare.org/book/search/since/02062008 *
    • api.bookshare.org/book/search/since/02062008/for/EMAIL_OF_END_USER  **
  • Errors:
    • Error 20 – Invalid date

Browse Latest

  • Description: List  books that have been published live on Bookshare within the last week. This is essentially a convenience method for the  Date Published Search listed above that defaults to the latest week.
  • Format: api.bookshare.org/book/latest
  • Authentication: Generally Available OR User Authenticated
  • Response: Book List Response
  • Example:
    • api.bookshare.org/book/latest *
    • api.bookshare.org/book/latest/for/EMAIL_OF_END_USER **

Browse Popular

  • Description: Search for books that have been downloaded the most times on Bookshare.
  • Format: api.bookshare.org/book/popular
  • Authentication: Generally Available OR User Authenticated
  • Response: Book List Response
  • Example:
    • api.bookshare.org/book/popular *

Category List

  • Description: Get a list of available book categories
  • Format: api.bookshare.org/reference/category/list
  • Authentication: Generally Available OR User Authenticated
  • Response: Category List Response
  • Example:
    • api.bookshare.org/reference/category/list

Category Search

  • Description: Search for books based on the category (see Category List to get valid category values).
  • Format: api.bookshare.org/book/search/category/Text
  • Authentication: Generally Available OR User Authenticated
  • Response: Book List Response
  • Example:
    • api.bookshare.org/book/search/category/Animals

Grade List

  • Description: Get a list of available grade categories
  • Format: api.bookshare.org/reference/grade/list
  • Authentication: Generally Available OR User Authenticated
  • Response: Category List Response
  • Example:
    • api.bookshare.org/reference/grade/list

Grade Search

  • Description: Search for books based on target grade level (see Grade List to get valid grade values).
  • Format: api.bookshare.org/book/search/grade/Text
  • Authentication: Generally Available OR User Authenticated
  • Response: Book List Response
  • Example:
    • api.bookshare.org/book/search/grade/First+grade
  • Errors:
    • Error 50 – Invalid/Incorrect Grade

Periodical Edition Search

  • Description: Look up the available editions, including revision numbers, of a given periodical that are in the Bookshare repository.
  • Format: api.bookshare.org/periodical/id/Number
  • Authentication: Generally Available OR User Authenticated
  • Response: Periodical List Response
  • Examples:
    • api.bookshare.org/periodical/id/14
    • api.bookshare.org/periodical/id/19
  • Errors:
    • Error 30 – Periodical not found

Periodical Edition Lookup

  • Description: Look up metadata about a given revision of a given edition of a specific periodical in the Bookshare repository. Revision is optional; if not specified, the default (latest) revision will be provided.
  • Format: api.bookshare.org/periodical/id/Number/edition/Date/revision/Number
  • Authentication: Generally Available OR User Authenticated
  • Response: Edition Metadata Response
  • Examples:
    • api.bookshare.org/periodical/id/14/edition/02202008/revision/3/
    • api.bookshare.org/periodical/id/19/edition/12192008/revision/1/
    • api.bookshare.org/periodical/id/19/edition/12192008/
  • Errors:
    • Error 30 – Periodical not found
    • Error 31 – Periodical edition not found
    • Error 32 – Periodical revision not found

Periodical List Search

Response Details

Metadata Responses

These responses provide metadata about the given revision or edition, including the content id which is necessary for download.

Common Fields

FieldTypeDescriptionOccurrence
content-idNumberId that can be used in Download Request1
daisyNumberIf 0, a DAISY download is not available. If 1, a DAISY download is available.0/1
brfNumberIf 0, a BRF download is not available. If 1, a BRF download is available.0/1

Book Metadata Response

Container: book/metadata

Fields

FieldTypeDescriptionOccurrence
isbn13TextThe 13 digit ISBN, if known0/1
authorTextThe, or one of the, author(s) of the book1/N
available-to-downloadNumberIf 0, it is not available for download (may be Subscription/Membership related). If 1, it is.1
titleTextThe title of the book1
publish-dateDateThe date published in bookshare1
publisherTextThe publisher of the book, if known0/1
copyrightDateThe date copyrighted, if known0/1
languageTextThe, or one of the, language(s) that the book is in0/N
brief-synopsisTextBrief Synopsis about this Periodical Edition0/1
complete-synopsisTextComplete Synopsis about this Periodical Edition0/1
categoryTextThe category this Edition belongs to0/N
bookshare-idTextThe Bookshare ID1
freely-availableNumberIf 0, it is not Freely Available. If 1, it is Freely Available.1
dtbook-sizeNumberSize of dbook in bytes0/1
download-formatTextFormat of download file.  For copyrighted titles, this attribute is only available for user authenticated requests and will only exist if available-to-download is 1.   Not all formats may be available to download via the API.0/N

XML Response Examples

Id not found

<bookshare>
  <status-code>0</status-code>
  <version>3.2.8</version>
  <messages>
    <string>Book not found</string>
  </messages>
</bookshare>

Invalid ISBN

<bookshare>
<version>3.5.0</version>
<messages>
<string>Invalid/Incorrect ISBN number</string>
</messages>
<status-code>85</status-code>
</bookshare>

Success

<bookshare>
  <version>3.2.8</version>
  <book>
    <metadata>
      <content-id>8191</content-id>
      <available-to-download>1</available-to-download> 
      <daisy>1</daisy>
      <brf>1</brf>
      <download-format>Daisy</download-format>
      <download-format>BRF</download-format>
      <download-format>DAISY with multiple DTBooks</download-format>
      <images>0</images>
      <isbn13>9780140177398</isbn13>
      <author>John Steinbeck</author>
      <title>Of Mice and Men</title>
      <publish-date>05142002</publish-date>
      <copyright>1965</copyright>
      <language>English US</language>
      <brief-synopsis>John Steinbeck tells the story of two friends who longed for a piece of land of their own.</brief-synopsis>
      <quality>Excellent</quality>
      <category>Literature and Fiction</category>
      <bookshare-id>8191_2617532</bookshare-id>
      <freely-available>1</freely-available>
      <dtbook-size>8232627</dtbook-size> 
    </metadata>
  </book>
</bookshare>

JSON Response Examples

Id not found

{"bookshare": {
  "version": "3.5.0",
  "messages": [
    "Book not found"
  ],
  "statusCode": "0"
}}

Invalid ISBN

{"bookshare": {
  "version": "3.5.0",
  "messages": [
    "Invalid/Incorrect ISBN number"
  ],
  "statusCode": "85"
}}

Id or ISBN lookup

{"bookshare": {
  "version": "3.5.0",
  "messages": [
  ],
  "book": {
    "metadata": {
      "author": [
        "John Steinbeck"
      ],
      "availableToDownload": 1,
      "bookshareId": "317647",
      "briefSynopsis": "They are an unlikely pair: George is \"small and quick and dark of face\"; Lennie, a man of tremendous size, has the mind of a young child. Yet they have formed a \"family,\" clinging together in the face of loneliness and alienation.",
      "category": [
        "Literature and Fiction"
      ],
      "completeSynopsis": "Laborers in California's dusty vegetable fields, they hustle work when they can, living a hand-to-mouth existence. For George and Lennie have a plan: to own an acre of land and a shack they can call their own. When they land jobs on a ranch in the Salinas Valley, the fulfillment of their dream seems to be within their grasp. But even George cannot guard Lennie from the provocations of a flirtatious woman, nor predict the consequences of Lennie's unswerving obedience to the things George taught him. ",
      "content-id": 317647,
      "copyright": "1965",
      "download-format": [
        "Daisy",
        "DAISY with multiple DTBooks",
        "BRF"
      ],
      "dtbookSize": 250306,
      "freelyAvailable": 0,
      "brf": 1,
      "daisy": 1,
      "images": 0,
      "isbn13": "9780140177398",
      "language": [
        "English US"
      ],
      "publishDate": "04142011",
      "publisher": "Penguin Group (Canada)",
      "quality": "Excellent",
      "title": "Of Mice And Men"
    }
  }
}}

Edition Metadata Response

Container: periodical/metadata

Fields

FieldTypeDescriptionOccurrence
editionDateThe edition date1
revisionNumberRevision of the edition, to be used in Periodical Edition Lookup1
revision-timeNumberTime in PST, 24H format; time that revision was received by Bookshare1
categoryTextThe category this Edition belongs to0/N

Xml Response Examples

Bad date

<bookshare>
  <status-code>20</status-code>
  <version>3.2.8</version>  
  <messages>
    <string>Invalid Date. Supported Format = MMDDYYYY</string>
  </messages>
</bookshare>

Edition not found

<bookshare>
  <status-code>31</status-code>
  <version>3.2.8</version>
  <messages>
    <string>Periodical Edition not found</string>
  </messages>
</bookshare>

Success

<bookshare>
  <version>3.2.8</version>
  <periodical>
    <metadata>
      <content-id>289934</content-id>
      <daisy>1</daisy>
      <brf>1</brf>
      <download-format>Daisy</download-format>
      <download-format>BRF</download-format>
      <images>0</images>
      <edition>01242011</edition>
      <revision>10</revision>
      <revision-time>0308</revision-time>
      <category>Maryland Newspapers</category>
    </metadata>
  </periodical>
</bookshare>

JSON Response Examples

Bad date

{"bookshare": {
  "version": "3.5.1",
  "messages": [
    "Invalid Date. Supported Format = MMDDYYYY"
  ],
  "statusCode": "20"
}}

Edition not found

{"bookshare": {
  "version": "3.5.1",
  "messages": [
    "Periodical Edition not found"
  ],
  "statusCode": "31"
}}

Revision not found

{"bookshare": {
  "version": "3.5.1",
  "messages": [
    "Periodical Revision not found"
  ],
  "statusCode": "32",
}}

Success

{"bookshare": {
  "version": "3.5.1",
  "messages": [
  ],
  "periodical": {
    "metadata": {
      "contentId": 372258,
      "daisy": 1,
      "brf": 1,
      "images": 0,
      "edition": "07272011",
      "revision": 1,
      "revisionTime": "0520",
      "categories": [
        "National Newspapers"
      ],
      "downloadFormats": [
        "Daisy",
        "BRF"
      ]
    }
  }
}}

List Responses

Lists resulting from a search.

Common fields

FieldTypeDescriptionOccurrence
pageNumberWhich page of results this represents1
limitNumberThe limit used when running the search1
num-pagesNumberThe number of pages of results at this value of limit1
resultContainerThe book/list (or) periodical/list Container0/N

Book List Response

Container: book/list/result

Fields

FieldTypeDescriptionOccurrence
idNumberBook id, to be used in Book Id Lookup1
titleTextTitle of the book1
authorTextThe author(s) of the book1/N
brief-synopsisTextBrief Synopsis about this Periodical Edition0/1
download-formatTextFormat of download file.  For copyrighted titles, this attribute is only available for user authenticated requests and will only exist if available-to-download is 1.   Not all formats may be available to download via the API.0/N
imagesNumberIf 1, indicates the book has images. 0 indicates it does not.1
isbn13TextThe 13 digit ISBN, if known0/1
publisherTextThe publisher of the book, if known0/1
freely-availableNumberIf 1, indicates the Book is Freely Available. 0 indicates it is not.1
available-to-downloadNumberIf 0, it is not available for download (may be Subscription/Membership related). If 1, it is.1
dtbook-sizeNumbersize of dtbook in bytes1

XML Response Examples:

No results found

<bookshare>
  <version>3.2.8</version>
    <messages>
      <string>No results found. You may need to broaden your search criteria.</string> 
    </messages>
    <book>      
      <list>
        <page>0</page>
        <limit>100</limit>
        <num-pages>0</num-pages>
      </list>
    </book>    
</bookshare>

Bad character

<bookshare>
  <status-code>10</status-code>
  <version>3.2.8</version>
  <messages>
    <string>Invalid Search Character</string>
  </messages>
  <book>
    <list>
      <page>0</page>
      <limit>100</limit>
      <num-pages>0</num-pages>
    </list>
  </book>
</bookshare>

Bad grade

<bookshare>
  <status-code>50</status-code>
  <version>3.2.8</version>
  <messages>
    <string>Invalid/Incomplete Request</string>
    <string>Invalid/Incorrect Grade</string>
  </messages>
  <book>
    <list>
      <page>0</page>
      <limit>5</limit>
      <num-pages>0</num-pages>
    </list>
  </book>
</bookshare>

Success

<bookshare>
  <version>3.2.8</version>
  <messages>
    <string>Results 1 - 5 of 4,281</string>
  </messages>
  <book>
    <list>
      <page>1</page>
      <limit>5</limit>
      <num-pages>857</num-pages>
      <result>
        <id>286066</id>
        <title>The Art of Fiction: Notes on Craft for Young Writers</title>
        <author>John Gardner</author>
        <brief-synopsis>The Art of Fiction will fascinate anyone interested in how fiction gets put together.</brief-synopsis>
        <images>1</images>
        <isbn13>9781609800482</isbn13>
        <publisher>Seven Stories Press</publisher>  
        <freely-available>0</freely-available>
        <available-to-download>0</available-to-download>
        <dtbook-size>560941</dtbook-size> 
      </result>
      <result>
        <id>286069</id>
        <title>Little Women</title>
        <author>Louisa May Alcott</author>
        <brief-synopsis>Little Women is one of the  best loved books of all time.</brief-synopsis>
        <images>1</images>
        <isbn13>9781583229958</isbn13>
        <publisher>Ten Speed Press</publisher>  
        <freely-available>0</freely-available>
        <available-to-download>1</available-to-download>
        <dtbook-size>1440654</dtbook-size> 
      </result>
      <result>
        <id>286071</id>
        <title>No-Fad Diet: A Personal Plan for Healthy Weight Loss</title>
        <author>American Heart Association</author>
        <brief-synopsis>By now, you've heard of (and maybe tried) them all: the low-carb diet, the grapefruit diet, the miracle diet</brief-synopsis>
        <images>1</images>
        <isbn13>9781583229958</isbn13>
        <freely-available>0</freely-available>
        <available-to-download>0</available-to-download>
        <dtbook-size>1814036</dtbook-size> 
      </result>
      <result>
        <id>286073</id>
        <title>The Feminine Face of God: The Unfolding of the Sacred in Women</title>
        <author>Patricia Hopkins</author>
        <author>Sherry Ruth Anderson</author>
        <images>1</images>
        <freely-available>0</freely-available>
        <available-to-download>1</available-to-download>
        <dtbook-size>835197</dtbook-size> 
      </result>
      <result>
        <id>286074</id>
        <title>To Thine Own Self Be True</title>
        <author>Lewis Andrews</author>
        <images>1</images>
        <freely-available>0</freely-available>
        <available-to-download>1</available-to-download>
        <dtbook-size>1127374</dtbook-size> 
      </result>
    </list>
  </book>
</bookshare>

Json Response Examples:

No results found

{"bookshare": {
  "version": "3.5.0",
  "messages": [
    "No results found. You may need to broaden your search criteria."
  ],
  "book": {
    "list": {
      "result": [
      ],
      "limit": 100,
      "num-pages": 0,
      "page": 0,
      "totalResults": 0
    }
  }
}}

Bad grade

{"bookshare": {
  "version": "3.5.0",
  "messages": [
    "Invalid/Incomplete Request",
    "Invalid/Incorrect Grade"
  ],
  "statusCode": "50",
  "book": {
    "list": {
      "result": [
      ],
      "limit": 100,
      "numPages": 0,
      "page": 0,
      "totalResults": 0
    }
  }
}}

Success

{"bookshare": {
  "version": "3.5.0",
  "messages": [
    "Results 1 - 3 of 2,131"
  ],
  "book": {
    "list": {
      "result": [
        {
          "author": [
            "Linda Hayward"
          ],
          "availableToDownload": 1,
          "briefSynopsis": "\"Brer Wolf is bigger. But! Brer Rabbit is smarter.\" A tale from Uncle Remus.",
          "downloadFormat": [
            "DAISY",
            "BRF"
          ],
          "dtbookSize": 12815,
          "freelyAvailable": 0,
          "images": 0,
          "isbn13": "9780394888644",
          "title": "Hello, House!"
        },
        {
          "author": [
            "Tricia Brown"
          ],
          "availableToDownload": 1,
          "briefSynopsis": "Follows a day, a birthday, in the life of a Mexican-American child who lives with his family in the Mission district of San Francisco.",
          "downloadFormat": [
            "DAISY",
            "BRF"
          ],
          "dtbookSize": 24569,
          "freelyAvailable": 0,
          "images": 0,
          "isbn13": "9780805018912",
          "publisher": "Henry Holt & Company",
          "title": "Hello, Amigos!"
        },
        {
          "author": [
            "Pam Muñoz Ryan"
          ],
          "availableToDownload": 1,
          "briefSynopsis": "Spend a day at the beach, and take in the ocean through the senses of sight, hearing, feeling, taste, and smell in this romp through sand and waves.",
          "downloadFormat": [
            "DAISY",
            "BRF"
          ],
          "dtbookSize": 14626,
          "freelyAvailable": 0,
          "images": 0,
          "isbn13": "9780439403177",
          "publisher": "Scholastic Inc.",
          "title": "Hello Ocean"
        }
      ],
      "limit": 3,
      "numPages": 711,
      "page": 1,
      "totalResults": 2131
    }
  }
}}

Category List Response

Container: category/list/result

Fields

FieldTypeDescriptionOccurrence
nameTextCategory name1

XML Response Example

<bookshare>
  <version>3.2.8</version>
  <messages>
    <string>Results 1 - 34 of 34</string>
  </messages>
  <category>
    <list>
      <page>1</page>
      <limit>100</limit>
      <num-pages>1</num-pages>
      <result>
        <name>Animals</name>
      </result>
      <result>
        <name>Art and Architecture</name>
      </result>
      <result>
        <name>Biographies and Memoirs</name>
      </result>
      ...
    </list>
  </category>
</bookshare>

JSON Response Example

{"bookshare": {
  "category": {
    "list": {
      "limit": 100,
      "numPages": 1,
      "page": 1
    },
    "result": [
      {
        "name": "Animals"
      },
      {
        "name": "Art and Architecture"
      },
      {
        "name": "Biographies and Memoirs"
      },
      {
        "name": "Business and Finance"
      },
      {
        "name": "Children's Books"
      },
      {
        "name": "Computers and Internet"
      },
      {
        "name": "Cooking, Food and Wine"
      },
      {
        "name": "Disability-Related"
      },
      {
        "name": "Educational Materials"
      },
      {
        "name": "Entertainment"
      },
      {
        "name": "Gay and Lesbian"
      },
      {
        "name": "Health, Mind and Body"
      },
      {
        "name": "History"
      },
      {
        "name": "Home and Garden"
      },
      {
        "name": "Horror"
      },
      {
        "name": "Literature and Fiction"
      },
      {
        "name": "Military"
      },
      {
        "name": "Mystery and Thrillers"
      },
      {
        "name": "Nonfiction"
      },
      {
        "name": "Outdoors and Nature"
      },
      {
        "name": "Parenting and Family"
      },
      {
        "name": "Poetry"
      },
      {
        "name": "Professional and Technical"
      },
      {
        "name": "Reference"
      },
      {
        "name": "Religion and Spirituality"
      },
      {
        "name": "Romance"
      },
      {
        "name": "Science"
      },
      {
        "name": "Science Fiction and Fantasy"
      },
      {
        "name": "Self-Help"
      },
      {
        "name": "Sports"
      },
      {
        "name": "Teens"
      },
      {
        "name": "Textbooks"
      },
      {
        "name": "Travel"
      },
      {
        "name": "Westerns"
      }
    ]
  },
  "version": "3.5.0",
  "messages": [
    "Results 1 - 34 of 34"
  ]
}}

Grade List Response

Container: grade/list/result

Fields

FieldTypeDescriptionOccurrence
nameTextGrade name1

XML Response Example

<bookshare>
  <version>3.2.8</version>
  <messages>
    <string>Results 1 - 14 of 14</string>
  </messages>
  <grade>
    <list>
      <page>1</page>
      <limit>100</limit>
      <num-pages>1</num-pages>
      <result>
        <name>Kindergarten</name>
      </result>
      <result>
        <name>First grade</name>
      </result>
      <result>
        <name>Second grade</name>
      </result>
      <result>
        <name>Third grade</name>
      </result>
      ...
    </list>
  </grade>
</bookshare>

JSON Response Example

{"bookshare": {
  "grade": {
    "list": {
      "limit": 100,
      "numPages": 1,
      "page": 1
    },
    "result": [
      {
        "name": "Kindergarten"
      },
      {
        "name": "First grade"
      },
      {
        "name": "Second grade"
      },
      {
        "name": "Third grade"
      },
      {
        "name": "Fourth grade"
      },
      {
        "name": "Fifth grade"
      },
      {
        "name": "Sixth grade"
      },
      {
        "name": "Seventh grade"
      },
      {
        "name": "Eighth grade"
      },
      {
        "name": "Ninth grade"
      },
      {
        "name": "Tenth grade"
      },
      {
        "name": "Eleventh grade"
      },
      {
        "name": "Twelfth grade"
      },
      {
        "name": "College Freshman"
      },
      {
        "name": "College Sophomore"
      },
      {
        "name": "College Junior"
      },
      {
        "name": "College Senior"
      },
      {
        "name": "Graduate Student"
      },
      {
        "name": "Adult Ed"
      },
      {
        "name": "Pre-Kindergarten"
      }
    ]
  },
  "version": "3.5.0",
  "messages": [
    "Results 1 - 20 of 20"
  ]
}}

Periodical List Response

Container: periodical/list/result

Fields

FieldTypeDescriptionOccurrence
idNumberPeriodical id, to be used in Periodical Edition Lookup1
editionDatePeriodical edition date, to be used in Periodical Edition Lookup. Not included in results from Periodical List Search0/1
revisionNumberRevision of the edition, to be used in Periodical Edition Lookup. Not included in results from Periodical List Search0/1
titleTextTitle of the periodical1

XML Response Examples

Bad Id

<bookshare>
  <status-code>30</status-code>
  <version>3.2.8</version>
  <messages>
    <string>Periodical not found</string>
  </messages>
</bookshare>

Success

<bookshare>
  <version>3.2.8</version>
  <messages>
    <string>Results 1 - 3 of 3</string>
  </messages>
  <periodical>
    <list>
      <page>1</page>
      <limit>100</limit>
      <num-pages>1</num-pages>
      <result>
        <id>46352</id>
        <edition>01252011</edition>
        <revision>4</revision>
        <title>Baltimore Sun</title>
      </result>
      <result>
        <id>46352</id>
        <edition>01242011</edition>
        <revision>10</revision>
        <title>Baltimore Sun</title>
      </result>
      <result>
        <id>46352</id>
        <edition>01232011</edition>
        <revision>15</revision>
        <title>Baltimore Sun</title>
      </result>
    </list>
  </periodical>
</bookshare>

JSON Response Examples

Bad Id

{"bookshare": {
  "periodical": {
    "list": {
      "results": [
      ]
    }
  },
  "messages": [
    "Periodical not found"
  ],
  "statusCode": "30"
}}

Success

{"bookshare": {
  "periodical": {
    "list": {
      "results": [
        {
          "id": 46289,
          "title": "Los Angeles Daily News",
          "edition": "07272011",
          "revision": 1
        },
        {
          "id": 46289,
          "title": "Los Angeles Daily News",
          "edition": "07262011",
          "revision": 1
        },
        {
          "id": 46289,
          "title": "Los Angeles Daily News",
          "edition": "07242011",
          "revision": 2
        }
      ]
    }
  },
  "messages": [
    "Results 1 - 3 of 3"
  ]
}}

** User Authenticated : available-to-download is dependent on end user rights

* Generally Available :  note that available-to-download is false/0 for copyrighted books