Bookshare Developer BlogRSS Feed
The latest update to our book download API allows you to request a new book format: DAISY with images. This kind of download request is considered asynchronous, because it triggers our system to begin packaging the (often large) files for use instead of instantly delivering the binary files. The addition of this new format means we've also updated our response structures so you can get book packaging status info while the book is being prepared. Asynchronous download requests may now get responses that indicate that book packaging is in progress, completed, or cancelled.
To do an asynchronous download like this, you can poll the status by making the same download request at some defined interval. Each time you will get a status response if the book is not ready, and when it is ready it will return the binary download, just as a normal download request does.
We've also updated the API I to allow retrieval of a month's worth of download history for an individual user, including author and title information, download format, and the packaging status for each book.
If you'll be at ATIA, come hear more about these changes on Thursday, Jan. 31, at 10 a.m. Eastern. The location of the meeting is still TBD, but you can get notification of the room by subscribing to our Twitter feed @BookshareAPI. As always, if you have any questions, please contact us via the Contact Us form.
We recently revised our DRM policy in order to better balance the need to protect copyright holders with the goal of simplifying the user and developer experience. As a result, a password is only required to authenticate Bookshare membership via the API and not to unzip downloaded titles. We will continue to require and enforce that all access via the API be done over secure HTTPS. To prevent unintended transmission of sensitive credentials, we have also announced that in the near future we will be preventing HTTP access for any API call.
If you have any questions, please contact us via the Contact Us form.
Bookshare provides the ability for members to view a history of their prior downloads. Members frequently access their download history to find books they have previously downloaded. Because of this, it is important that you use a user authenticated download request, if you know who the current user is, even when downloading freely-available titles.
If you application is not following this approach, please change it as soon as possible. Please let us know, if you have any questions.
The introduction of the Digital Accessible Information System, or DAISY, was a transformative event. Prior to DAISY most print-disabled users relied on Braille or recorded audio to consume books. Print readers take for granted the ability to identify structure and meaning from visual formatting and layout, as well as the ease with which they can navigate to specific sections of a book by using chapter headings and page numbers.
It's a different story when using the fast forward button while playing back a cassette tape, or skimming past a linear stream of Braille. DAISY leveraged the multimedia capabilities of computers in the late 90s, bringing together digital audio, structured text, and support for fine-grained navigation. DAISY books can be adapted for a variety of needs: Braille output for blind readers, large type and high contrast display for users with low vision, even word-by-word text highlighting with synchronized text-to-speech for individuals with learning disabilities. DAISY truly is a better way to read, not just for print-disabled readers, but for everyone!
Bookshare members have a wide spectrum of needs, and DAISY has allowed us to provide accessible resources to each and every one of them. In recent years Bookshare's particular focus has been on making the resources of the National Instructional Materials Access Center more readily available to students in the United States, and that has brought with it certain challenges.
As anyone who remembers lugging a backpack to school can attest to, textbooks are quite large. There is a tremendous amount of content in them, and it is very carefully organized in a deep and detailed structure.
The foundation for DAISY's structured text storage is the eXtensible Markup Language. Flexible, adaptable, and supported by a wide variety of existing tools, XML's expressiveness lends itself well to the rich content in textbooks.
However, that flexibility comes at a cost. Loading XML can be very memory-intensive, especially when using more robust models that allow developers to locate and manipulate XML data at a very fine level. If the loading process isn't optimized, even desktop computers can struggle to load large textbooks.
This is even more true of portable devices like Braille notetakers, smartphones, and tablets, which have less RAM and processing power available. A portable device may easily handle a National Federation for the Blind edition of the Los Angeles Times or the latest New York Times bestseller, but parsing the XML for even a relatively small textbook can result in crashes or unacceptably slow load times.
Portable devices are getting more capable every year, and mobile operating systems like Android and iOS are making great strides in accessibility support. This is the transformative wave of the moment, as mobile computing becomes an essential part of people's lives, including the print-disabled community.
Anyone who develops software for portable devices knows that care must be taken to stay within their memory and processing constraints. Bookshare must also take the same kind of care to make sure that our books provide the best reading experience possible for these devices, so we are rolling out updates to how we package our largest books.
Most DAISY books contain only a single structured text file, which is consistent with the guidance in the DAISY specification. XML is typically not loaded progressively; it must be loaded and parsed all at once, which causes DAISY readers to suffer from long load times, reduced responsiveness, and in the worst cases, crashes.
Fortunately the specification allows for splitting the text content across multiple DTBook files.
A DTB that includes textual content will, in most cases, contain only one textual content file. However, when necessary (with a very large book, for example), a DTB can contain multiple textual content files, each of which must be valid to the DTBook DTD.
So a DAISY package that once looked like this:
Can be repackaged like this:
The playback, synchronization, and navigation components of a DAISY book would remain largely the same; the only change is that the sourcing of text content would come from multiple files rather than just one. By splitting the text content, a DAISY reader only needs to load small segments of the entire text at a time. This allows the content being viewed to fit within limited available RAM, improving load times and responsiveness.
For books in our collection that have a textual content file in excess of 2 MB, we create a second, segmented version of the DAISY book with individual DTBook files no larger than 1 MB. For example, a textbook that weighs in at 25 MB would be split into 25 separate files of 1 MB or less. Our testing has shown that loading and navigating through such segmented books speeds up by at least a factor of 2, and in some cases can be 6 to 8 times faster.
Outside of Bookshare's textbook collection, most DAISY books are smaller works or audio-only, and the DAISY convention of one textual content file per book has held up very well. But this is only a convention; the DAISY specification gives us clear guidance for handling larger books.
Because this convention has prevailed for so long, some DAISY readers simply assume that there is only one textual content file and cannot read these books properly. However, there are other readers that handle these files just fine, most notably the DAISY Consortium's Amis, the APH's Book Wizard software and Book Port Plus portable player, and Bookshare's own Read2Go app for iOS.
Some makers of assistive technology products have addressed large books by investing a lot of work into highly-optimized XML parsing. But for those who have not, and indeed even for those who have, our segmented DAISY books can help unburden you from under-the-hood optimizations, allowing you to devote more time to focus the kinds of features that delight and engage your users.
Segmented books are currently available only via the Bookshare API. If you have not signed up for an API key, you can request one here.
To get a segmented book:
- Perform a book search
- Check the
<result>elements for the
<download-format>elements that indicate the formats each book is available in.
- Large books will include a
<download-format>element with the value "DAISY with multiple DTBooks".
- You can download the segmented version of a large book by using the format id 2 instead of the typical 0 (for BRF) or 1 (for DAISY)
We welcome your feedback and hope we can continue collaborating on improvements like segmented DAISY that can enhance the experiences of all our users.
We've been hard at work listening to your suggestions and enhancing our API over the last few months.
- As requested by ATPC, we've enhanced our book search results to include publisher and ISBN information. We also added brief synopsis to the book search results. We feel that this will be a big win for your users as this should reduce the need for them to make indivual book metadata calls based on search results to get this information. These new fields are documented here.
- Another big feature we've introduced, as requested by both LevelStar and Internet Archive, is the introduction of JSON as a possible format for our API responses. The ability to return JSON is documented here.
Another exciting feature is the ability to test out the API in realtiime without having to write a single line of code. You will need an API key and you can try this out here.
Finally, we'd like to leave you with a performance tip. In our experience, most users want to do a title/author search when they enter a search keyword, and this can be accomplished by making the default search call to /book/search/ . The default search call is three time faster than the full text search call , so we'd suggest only making the full text search call when the user really intends to search the entire contents of the book.
Don't forget to subscribe to this blog to be automatically alerted when we update it!
It was great to see a number of you at CSUN in San Diego this year! I felt like I could barely get around the exhibition floor, but I tell you talking to so many people is always just a huge encouragement and great to see people in real life! Thanks for those of you that stopped by or were able to connect.
Just wanted to give you a few quick updates:
- We released an update to the web service that includes a new function to get user name and user ID. This is primarily done so that we can support single sign-on to 3rd parties integrating our 'feedback forum' hosted by Uservoice.
- We are continuing to encourage that those of you that have been long-time users of our API please look to move off of the old authentication calls to "service" and start using the new Mashery API authentication calls. This means you will no longer require a Bookshare webservice account to be managed and maintained by us. We also eventually want to deprecate the old service system and support everyone on the more scalable, self-service model here on Mashery. Details on the changes are documented here.
- Many of our legacy users may have noticed that our book search results now give you many more results than they have previously. This is because we previously had a database fielded search and moved off of that to a true search engine (Solr) to deliver our search results. This means it's more performant and also will support the feature of full text search (which is available to you today). It also means that it has implemented new search semantics - the way you do searches is slightly different and the search results also implement a "phonetic" or "sounds like" component that allows for a wide degree of misspelling to be accounted for in the search. However, searches should deliver the most accurate results weighted by a relevancy algorithm at the top of the list (Title and Author are weighted most high in the algorithm). We are planning on improvements to this search capability, but there are details on how to search on our website in the support portal.
Don't forget to Subscribe to this page to be automatically alerted when we update it!
Welcome to the Bookshare Developer Network Blog. We are pleased to launch our new Developer Network Portal in time for the ATIA Conference in Orlando. This new site will guide Assistive Technology (AT) Partners and other 3rd party developers through how to easily integrate their applications and devices with Bookshare’s API.
The Bookshare API (aka web service) allows our partners to enable their customers with qualified print disabilities to search, browse and download books and periodicals directly from our partner’s applications and devices. Be sure to check out our Partner Gallery to see how various partners have integrated with the Bookshare API.
We will be demonstrating the new Developer Network Portal and API enhancements at ATIA on Friday January 28th from 1:15pm to 2:15pm at the Bookshare team Villa 6504. Come by our booth to get more details or contact us directly at firstname.lastname@example.org.
Existing Bookshare API developers will want to check out the migration guide, which explains the minor modifications they need to make for taking advantage of new API features. New developers will want to start by reading the Getting Started documentation.
We value any ideas our partners and developers have, so be sure to provide ideas or vote on feature requests via our UserVoice forum, which can be accessed via the “feedback” tab on the right side of the Developer Portal. We have also created a forum area where partners and developers can discuss issues and topics.
Along with launching the Developer Network Portal, we have enhanced the Bookshare API to enable the following functionality:
- Browse latest books available on Bookshare
- Browse popular books
- Full Text Search across the title, author and content of a book
- Enhanced search across the title
- Enhanced search across the author
- Enhanced search across the title and author
- Enhanced category search
- Get a list of grade categories for filtering searches
- Grade category search for textbooks and other books
In case you were not already aware, we previously enhanced the API to include an "available to download" field in the search and browse reponses and the ability for organizational members (e.g. teachers) to download books.
Finally, we would like to thank Mashery for helping us create a fantastic new experience for our partners who will ultimately create new technological solutions to serve people with print disabilities.
[ Page 1 of 1 ]