Search and Browse

Summary of Book Requests

URI Details Response
api.bookshare.org/book/isbn/Text ISBN Lookup Book Metadata Response
api.bookshare.org/book/id/Number Book Id Lookup Book Metadata Response
api.bookshare.org/book/searchFTS/Text Full Text Search Book List Response
api.bookshare.org/book/search/title/Text Title Search Book List Response
api.bookshare.org/book/search/author/Text Author Search Book List Response
api.bookshare.org/book/search/Text Title/Author Search Book List Response
api.bookshare.org/book/search/since/Date Date Published Search Book List Response
api.bookshare.org/book/latest Latest books added to Bookshare Book List Response
api.bookshare.org/book/popular Popular books on Bookshare Book List Response
api.bookshare.org/reference/category/list Category List Category List Response
api.bookshare.org/book/search/category/Text Category Search Book List Response
api.bookshare.org/reference/grade/list Grade List Grade List Response
api.bookshare.org/book/search/grade/Text Grade Search Book 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

URI Details Response
api.bookshare.org/periodical/id/Number Periodical Edition Search Periodical List Response
api.bookshare.org/periodical/id/Number/edition/Date/revision/Number Periodical Edition Lookup Edition Metadata Response
api.bookshare.org/periodical/list Periodical List Search Periodical 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

Field Type Description Occurrence
content-id Number Id that can be used in Download Request 1
daisy Number If 0, a DAISY download is not available. If 1, a DAISY download is available. 0/1
brf Number If 0, a BRF download is not available. If 1, a BRF download is available. 0/1

Book Metadata Response

Container: book/metadata

Fields

Field Type Description Occurrence
isbn13 Text The 13 digit ISBN, if known 0/1
author Text The, or one of the, author(s) of the book 1/N
available-to-download Number If 0, it is not available for download (may be Subscription/Membership related). If 1, it is. 1
title Text The title of the book 1
publish-date Date The date published in bookshare 1
publisher Text The publisher of the book, if known 0/1
copyright Date The date copyrighted, if known 0/1
language Text The, or one of the, language(s) that the book is in 0/N
brief-synopsis Text Brief Synopsis about this Periodical Edition 0/1
complete-synopsis Text Complete Synopsis about this Periodical Edition 0/1
category Text The category this Edition belongs to 0/N
bookshare-id Text The Bookshare ID 1
freely-available Number If 0, it is not Freely Available. If 1, it is Freely Available. 1
dtbook-size Number Size of dbook in bytes 0/1
download-format Text

Format 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

Field Type Description Occurrence
edition Date The edition date 1
revision Number Revision of the edition, to be used in Periodical Edition Lookup 1
revision-time Number Time in PST, 24H format; time that revision was received by Bookshare 1
category Text The category this Edition belongs to 0/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

Field Type Description Occurrence
page Number Which page of results this represents 1
limit Number The limit used when running the search 1
num-pages Number The number of pages of results at this value of limit 1
result Container The book/list (or) periodical/list Container 0/N

Book List Response

Container: book/list/result

Fields

Field Type Description Occurrence
id Number Book id, to be used in Book Id Lookup 1
title Text Title of the book 1
author Text The author(s) of the book 1/N
brief-synopsis Text Brief Synopsis about this Periodical Edition 0/1
download-format Text Format 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
images Number If 1, indicates the book has images. 0 indicates it does not. 1
isbn13 Text The 13 digit ISBN, if known 0/1
publisher Text The publisher of the book, if known 0/1
freely-available Number If 1, indicates the Book is Freely Available. 0 indicates it is not. 1
available-to-download Number If 0, it is not available for download (may be Subscription/Membership related). If 1, it is. 1
dtbook-size Number size of dtbook in bytes 1

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

Field Type Description Occurrence
name Text Category name 1

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
name Text Grade name 1

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

Field Type Description Occurrence
id Number Periodical id, to be used in Periodical Edition Lookup 1
edition Date Periodical edition date, to be used in Periodical Edition Lookup. Not included in results from Periodical List Search 0/1
revision Number Revision of the edition, to be used in Periodical Edition Lookup. Not included in results from Periodical List Search 0/1
title Text Title of the periodical 1

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"
  ]
}}

 

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

 

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

 

 

1 Comment

  1. thushan5 years ago

    Hi, Does Bookshare allow requests for periodical details as followed https://api.bookshare.org/periodical/id/<id>/edition/<edition>/revision/<revision>/for/<Sponsor_Account>?api_key=<api_key> I keep getting 'Error 31'. I know that the periodical I requested is a valid periodical.

    Thanks in Advance

Please sign in to post a comment.