Download

URI Details Response
api.bookshare.org/download/content/Number/version/Number Generally Available Download Request Book Packaging Status or Binary Download
api.bookshare.org/download/content/Number/version/Number/for/Text User Authenticated Download Request

Book Packaging Status or Binary Download

api.bookshare.org/download/member/Text/content/Number/version/Number/for/Text Organizational Download Request Book Packaging Status or Binary Download

Download Request Details

  • Description: Download the periodical edition or book based on the content-id in the Metadata Response. The user who the download request is being made for can be specified when requesting non-generally available content using the for parameter. If the book requires additional time to package for download, a Book Packaging Status will be returned instead of the actual book. The same download request can be repeated until the packaging is finished, at which point the response will be a Binary Download.
  • Available versions (depending on indication of availability in the response):
  • Format for user authenticated requests: api.bookshare.org/download/content/Number/version/Number/for/Text, where the for parameter specifies the email address/username of the end user for whom the download is being requested for.  In addition the MD5 hash of the end user password must be passed in the request via a "X-password" HTTP header.
  • Format for generally available requests: api.bookshare.org/download/content/Number/version/Number.  Only use generally available requests for freely-available content, if the user is anonymous.  When you make a generally available download request, the request is not logged in the user's download history and may cause confusion to the end user.
  • Authentication: Generally Available only if metadata response indicates it is freely-available AND user is anonymous.  Otherwise use User Authenticated
  • Response: Book Packaging Status if the book requires additional time to package for the user and is not yet ready for download, or Binary Download. 
  • Examples:
    • api.bookshare.org/download/content/1892124/version/0/for/user@foo.com
    • api.bookshare.org/download/content/1892124/version/1/for/user@foo.com
    • api.bookshare.org/download/content/1892124/version/1 (When it's freely-available Content AND the user is anonymous)
    • Example using curl and passing the end user password via the X-password HTTP header:
curl -k -H "X-password:MD5_OF_ENDUSER_PASSWORD" \
https://api.bookshare.org/download/content/250448/version/1/for/EMAIL_OF_END_USER?api_key=YOUR_API_KEY
  • Errors:
    • Error 40 - Content not available
    • Error 41 - Content not available to user
    • Error 42 - Content not available in requested format
    • Error 60 - The Web Service account does not have permission to download the content

* Formats that are not immediately available for download:

These formats require packaging of the title for the specific member and will be available for download upon packaging completion. 
 See Book Packaging Status below to determine when the packaged file is ready for download.
  • DAISY with Images
  • EPUB 3 - If EPUB 3 is not already prepared for downloads, the Download Request in EPUB 3 automatically initiates the preparation of an EPUB 3 format, as well as the packaging of the download for the specific member. Some titles are too complex to be processed on-the-fly as an EPUB 3, so may result in an error; please do check packaging status.
  • PDF - This format type is available for a limited set of titles that will be available to RNIB student members as part of a private collection.
  • DAISY Audio

Organization Download Request Details

  • Description: Download the periodical edition or book based on the content-id in the Metadata Response. The Sponsor of an Organization is specified in the for parameter and the Organization Member for whom the download is being made for is specified in the member parameter. In addition the MD5 hash of the end user password must be passed in the request via a "X-password" HTTP header.  Available versions are BRF (0), DAISY (1) or DAISY with multiple DTBooks (2) (depending on indication of availability in the response). Download for a Member should include the Obfuscated Member ID returned in Member List Response.
  • Format: api.bookshare.org/download/member/text/content/Number/version/Number/for/Text
  • Authentication: Generally Available only if metadata response indicates it is freely-available AND user is anonymous.  Otherwise use User Authenticated
  • Response: Binary Download
  • Examples:
    • api.bookshare.org/download/member/1234567890/content/1892124/version/0/for/user@foo.com
    • api.bookshare.org/download/member/987654321/content/1892124/version/1/for/user@foo.com
  • Errors:
    • Error 13 - Member ID specified does not exist.
    • Error 61 - Unauthorized request. The User is not associated with an Organization.
    • Error 82 - The Member for whom a NIMAC title is being downloaded requires to have IEP certificate. This can be set at Bookshare.org site by the Sponsor.

Additional Information on Organization Member Download of NIMAC Titles

  • Organizations attempting to download NIMAC titles must have the following criteria met before their Sponsors can download NIMAC titles. Currently there is no way to work around these errors via Web Service.
  • The Sponsors need to log into their Bookshare.org Sponsor accounts and work with Support if they are not authorized to download NIMAC titles.
    • The Organization should be approved by a Bookshare Admin that their Sponsor can download NIMAC Books.
    • An Organization Member must have IEP Certificate set before the Sponsor can download a NIMAC title for them. The Sponsor can set this for their Members in their Roster at Bookshare.org.

Book Packaging Status

Container: book

Fields

FieldTypeDescriptionOccurence
content-id Number Id that can be used in download request 1
packaging-status Text

The current status of the download. One of the following:

SUBMITTED: The request is queued up waiting to be handled

IN_PROGRESS: It is in the process of being prepared for download

CANCELLED: There was an error during the packaging and is not currently available.

1

XML Example

<bookshare>
  <version>4.0.2</version>
    <messages>
      <string>Submitted</string> 
    </messages>
    <book>
        <content-id>123456</content-id>
        <packaging-status>SUBMITTED</packagingStatus>
    </book>
</bookshare>

Binary Download

  • A zip containing either a BRF or DAISY package.