1. Overview
The Bookshare API v2 provides clients the ability to offer access to the collections managed by Bookshare for both registered users and guests. The API v2 aims to conform closely to REST constraints and API norms in order to make it as understandable and consistent to use as possible.
In order to use the API, you will need to have an API key for each client application. You can request one by emailing partner-support@bookshare.org with details of the application you are developing. The API key then needs to be included as a request parameter named "api_key" on all endpoints. For example,
https://api.bookshare.org/v2/titles?title=Tom+Sawyer&api_key=123451.1. Media Types
The Bookshare API supports JSON as the response format, with UTF-8 as the expected encoding. The description of each endpoint will have an example of a request and response structure to give you a sense of what they are like. Note that form data should be URL-encoded if it is sent as the default media type, "x-www-form-urlencoded." For background, see RFC1738 for a description of characters that require encoding.
When parsing the response, clients should ignore any fields in the response structure that they don’t recognize. New fields may be added as the API expands or as more information about a resource becomes available.
1.2. Authentication and Authorization
The API v2 uses OAuth 2.0 for authorization, and for authentication flow. See the authorization documentation for details.
1.3. Hypermedia
Most resources will have elements in a "links" object that represent related resources. These are there for you to avoid having to construct URLs yourself, and to reduce the impact of URL changes.
Links are constructed in the HAL style. For example, the most common link, the "self" relation, will look like this for a reading list whose identifier is 100:
"links" : [ {
"rel" : "self",
"href" : "https://api.bookshare.org/v2/lists/100"
} ]The other properties that might appear on a link are "title", which would provide suggested text for the link title, and "type", which would provide the media type you should expect from the link endpoint in the cases where it isn’t JSON. For example, a link to an administrative interface that might be returned for users with a Collection Assistant role might look like this:
"links" : [ {
"rel" : "metadata",
"href" : "https://xyz.bookshare.org/abc/12345",
"title" : "Edit title metadata",
"type" : "text/html"
} ]The links that appear will depend on the context, and will have descriptive relationships. For example, the reading list resource will have a "titles" link referring to the resource to retrieve the titles on the list.
All resources that have links will have at least one, the "self" link, which provides the canonical reference to this resource.
1.4. Capabilities
The operations allowed on a resource can depend on factors like the user, the title, or the site. These operations are presented in the "allows" field of the resource as HTTP verbs, representing those that can be used on the "self" link by the requesting user. For example, a reading list titles resource represents a collection of titles, where others may be able to retrieve this resource, but only the owner can make changes to it. A user who can only view the list might get a response that looks like this (fields have been removed here for clarity):
{
"readingListId" : 100,
"allows": [ ],
"titles" : [ {
"bookshareId" : 123456,
"title" : "Tom Sawyer",
"allows" : [ ]
"links" : [ {
"rel" : "self",
"href" : "https://api.bookshare.org/v2/lists/100/titles/123456"
} ]
} ],
"links" : [ {
"rel" : "self",
"href" : "https://api.bookshare.org/v2/lists/100/titles"
} ]
}The owner of the list, on the other hand, would receive a resource structure that indicates that they can add a new title to the list, and can remove a specific title. The "allows" property will be on the resource that the verb can apply to, so they would see a "POST" allowed on the reading list resource, and a "DELETE" allowed on the reading list title resource:
{
"readingListId" : 100,
"allows" : [ "POST" ],
"titles" : [ {
"bookshareId" : 123456,
"title" : "Tom Sawyer",
"allows" : [ "DELETE" ]
"links" : [ {
"rel" : "self",
"href" : "https://api.bookshare.org/v2/lists/100/titles/123456"
} ]
} ],
"links" : [ {
"rel" : "self",
"href" : "https://api.bookshare.org/v2/lists/100/titles"
} ]
}So while the endpoint to add a title to a reading list can be accessed by anyone, the "allows" value in the reading list resource indicates whether it would be allowed for the given user. For the owner of the list, they will get a successful response to adding a title, while the read-only user above would get an error response if they tried adding a title.
The possible "allows" values are the common HTTP action verbs (GET, POST, PUT, DELETE). Their meaning in the context of a specific resource is described in the resource documentation. For example, see the reading list resource description.
Note: This property mimics the purpose of the "Allow" HTTP header. We are using a property here since resource definitions may contain nested resource definitions, and the "allows" property lets us distinguish the capabilities of each resource within the response.
1.5. Pagination
When a list of resource results contains more resources than be reasonably returned in one call, the result will include a count of the total resources found, the number returned, and a "next" token that can be used to retrieve the next set of results. The simplest way to get the next set of results is to use the "next" link that also appears in the result. You will see that it is the "self" link, with an additional "start" parameter that contains the value of this "next" token.
For example, you could search for books with the title "Tom Sawyer" with this curl command:
curl https://api.bookshare.org/v2/titles?title=Tom+Sawyer\&api_key=12345The results you get back might look like this:
{
"totalResults": 179,
"limit": 10,
"next": "abcde",
"titles": [
...
],
"links": [
{
"rel": "self",
"href": "https://api.bookshare.org/v2/titles?title=Tom Sawyer&api_key=12345"
},
{
"rel": "next",
"href": "https://api.bookshare.org/v2/titles?title=Tom Sawyer&api_key=12345&start=abcde"
}
]
}You can control the page size with the "limit" parameter, which should be an integer between 1 and 100. If you don’t specify it, you will get a reasonable page size, and if you specify too large a number, it will simply be capped at 100.
1.6. Multi-valued Parameters
When an endpoint parameter is described in the "Schema" column as being a multi-valued parameter, such as categories in "Search for titles", then you can specify multiple values by including the parameter multiple times.
For example, you could search for books that are in either the category "Animals" or "Language Arts" with this curl command:
curl https://api.bookshare.org/v2/titles?categories=Animals\&categories=Language+Arts\&api_key=123451.7. Response Codes
The API v2 will respond with one of the standard HTTP response codes with any call. The ones you may see from this API are listed here for quick reference. Any specific information about the status will be returned in text in the body of the response.
| Status Code | Meaning |
|---|---|
200 |
Request successful. |
201 |
Resource was created, see 'Location' header for the URI. |
202 |
Resource was accepted, and processing will be done at some time in the future. The response body may have further status information and message text. |
204 |
Resource was deleted, no response body needed. |
301 |
Resource moved permanently, see 'Location' header for the new URI. |
302 |
Resource is temporarily found under a different URI, see 'Location' header for the new URI. |
400 |
Error in the request format. See the response body for more information. If this is the result of validating user input, the response body should have information about how to correct specific input values. |
401 |
Requesting user has not been authenticated. |
403 |
Requesting user is not authorized for the given resource. |
404 |
Resource not found for the requesting user. |
405 |
Method not supported. See the 'Allow' header for supported method. |
406 |
Invalid 'Accept' header was sent. The only allowed value is 'application/json'. |
409 |
Resource exists (duplicate resource creation was requested). |
415 |
Media type of the request is not valid. The only allowed value is 'application/json'. |
429 |
Too many requests. The client has sent too many requests in a given amount of time. The request may be retried later. |
500 |
Internal server error. The service is unable to process the resource request, and it can be tried later. |
Since all responses will be in JSON, any error response body will be JSON as well. The Error has a key and a messages field, so a 401 response body might look like this:
{
"key": "UNAUTHORIZED",
"messages": [
"Must be authenticated to download."
],
"links": []
}If a user tried to create a reading list without providing a required "name" value, the status code would be 400, and the response body might look like this:
{
"key": "BAD_REQUEST",
"messages": [
"Name is required"
],
"links": []
}1.8. Alerts
A successful response status may still have information in it that should be conveyed to the user as information about their request. For example, a request to download a title might return a 403 status if the user is not authorized to download it, but a request for the title metadata could return a 200 success status along with one or more alerts that might explain why a download request would not be allowed. These alerts will contain default message text that could be used along with an alert level and an alert code that a client could use to present messaging of their own. The table of alert codes lists the currently defined codes that might be returned in a resource.
1.9. Dates
Unless otherwise indicated, date fields will be in one of the formats described by the W3C profile of the ISO 8601 formats:
-
Four-digit year, for fields like copyright date of a title.
-
Calendar date, as 'YYYY-MM-DD', for precision to a given day, such as a user’s birth date.
-
Complete date plus hours, minutes and seconds, as 'YYYY-MM-DDThh:mm:ssTZD', where the time zone designator 'TZD' is 'Z' to represent zone UTC+0. For example,
1988-08-30T12:00:00Zrepresents August 30, 1998, 12:00 PM at UTC+0.
1.10. User Types
The authenticated users who interact with the system through an API client can have several different roles. Their role will determine the resources they are able to work with, and the actions they can take on them. The resource definitions that follow should give a sense of which roles each applies to, but as an API developer, the best determinant of whether a resource should be offered to a user will be the presence or absence of links within the resources at runtime, and the capabilities definitions.
An API client is not required to support all types of users. The descriptions here are meant to give an idea of the scope of work that a user of each type would want to perform, and therefore what sets of resources a client would need to implement in order to support them.
The following are the different roles that users might have:
-
Individual Member: These are users who have a personal subscription to the Bookshare service, and are able to get books on their own behalf. These users have the most straightforward interaction with the system. They may also be, simultaneously, organization members who get some benefits from organization membership, such as use of the organization’s subscription.
-
Organization Sponsor: These are users who represent members of an organization, such as a school or a library, who only get books for others on their behalf. For example, a teacher at a school will have the role of sponsor, and will get books on behalf of their students. A sponsor may be responsible for a few members or hundreds of members, and an organization may have a few or many sponsors. Many of the resources specifically designed for sponsors will be described in the "Organization" section.
-
Organization Member: These are users who also represent members of an organization, but are often minors or users who don’t regularly use the service themselves. Organization members may have usernames with which they can authenticate and interact with the system, or they may not. Organization members are typically limited in what titles they can get on their own, which will be reflected in the presence or absence of download links when they search for titles.
-
Collection Assistant: These are administrative users who have the right to manage elements of the collection that belong to their site, either adding and removing titles, or updating the metadata of titles. The resources specifically designed for these users are described in the Collection Management documentation.
-
Membership Assistant: These are administrative users who have the right to manage user accounts that belong to their site, either updating aspects such as subscriptions or proof of disability, creating new users, or looking up information about users. The resources specifically designed for these users are described in the Membership Management documentation, but note that these resources are only available to a limited set of clients in order to protect the personal information of users.
-
Administrator: These are administrative users who have the abilities of both Collection Assistants and Membership Assistants, and whose visibility lets them manage users or collections that belong to any site.
-
Volunteer: These are users who help to add new items to the collection, but with fewer rights than Collection Assistants. They can submit and proofread scanned titles, but are not approved members so cannot download other titles. Note: The API does not yet have resources supporting Volunteer users.
-
Guest: These are unauthenticated users, meaning that requests are made without an OAuth token. Guests are allowed to do things like search the collection and download, but the resources that will return with a download link will be limited to those that are either in the public domain, or have a Creative Commons license.
1.11. Sites
The Bookshare API provides access to the entire Bookshare platform, which hosts users and catalogs for different entities, or "sites". For example, Bookshare hosts the collections of the Royal National Institute of Blind People (RNIB) and the Centre for Equitable Library Access (CELA), among others, while keeping the rights of their users and catalogs partitioned according to access rules.
An API client does not need to know or care about the site that an authenticated user is associated with, since the access rules within the Bookshare system will limit the views of users and titles for them. However, an API key is associated with a particular site as well, which will apply if a guest user interacts with the Bookshare API. In that case, the guest user will have their view of the collection limited to that defined by the site associated with the API key. The site association of an API key will be defined at the time of generating an API key.
While most API clients will likely focus on supporting access to members of a particular site, the API does not currently limit user accounts to particular clients.
2. Endpoints
2.1. Assigned Titles
Assigned titles are titles that have been assigned to an organization member by a sponsor of that organization.
2.1.1. Get my assigned titles
GET /v2/myAssignedTitles
Description
As an organization member, get titles that have been assigned to me.
Parameters
Query Parameters
| Name | Description | Required | Schema | Default |
|---|---|---|---|---|
start |
If null or empty, it means to start at the beginning of the result set. Otherwise, it should be the value of 'next' that was returned from the previous request. |
- |
String |
null |
limit |
Maximum number of results to include. The maximum allowed is 100. |
- |
Integer |
10 |
sortOrder |
Primary sorting field. |
- |
enum [title, author] |
[title] |
direction |
Direction for sorting. |
- |
enum [asc, desc] |
[asc] |
Responses
| HTTP Code | Message | Datatype |
|---|---|---|
200 |
Title metadata collection response. |
|
0 |
Unexpected error |
Example HTTP request
GET /v2/myAssignedTitles?api_key=abcdefg HTTP/1.1
Host: api.bookshare.orgExample HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 2711
{
"limit" : 10,
"next" : null,
"totalResults" : 1,
"allows" : null,
"titles" : [ {
"allows" : null,
"bookshareId" : 1041744,
"title" : "The Adventures of Tom Sawyer",
"subtitle" : null,
"authors" : [ {
"firstName" : "Mark",
"lastName" : "Twain",
"middle" : null,
"prefix" : null,
"suffix" : null,
"links" : [ ]
} ],
"isbn13" : "9781551998121",
"synopsis" : "The classic boy-hero of American literature.",
"seriesTitle" : null,
"seriesNumber" : null,
"copyrightDate" : null,
"publishDate" : "2015-05-08T00:00:00Z",
"formats" : [ {
"formatId" : "DAISY",
"name" : "DAISY"
}, {
"formatId" : "BRF",
"name" : "BRF"
}, {
"formatId" : "DAISY_AUDIO",
"name" : "Audio"
}, {
"formatId" : "EPUB3",
"name" : "EPUB 3"
} ],
"externalFormats" : [ ],
"titleContentType" : "text",
"available" : true,
"contributors" : [ {
"name" : {
"displayName" : "Mark Twain",
"indexName" : "Twain, Mark",
"links" : [ ]
},
"type" : "author"
} ],
"composers" : null,
"lyricists" : null,
"arrangers" : null,
"translators" : null,
"editors" : null,
"instruments" : null,
"vocalParts" : null,
"languages" : [ "eng" ],
"contentWarnings" : [ ],
"categories" : [ {
"name" : "Literature and Fiction",
"description" : "Literature and Fiction",
"categoryType" : "Bookshare",
"code" : null,
"links" : [ ]
}, {
"name" : "FICTION / Action & Adventure",
"description" : "FICTION / Action & Adventure",
"categoryType" : "BISAC",
"code" : "FIC002000",
"links" : [ ]
} ],
"readingAgeMinimum" : 10,
"readingAgeMaximum" : 16,
"lexileCode" : "HL",
"lexileNumber" : "750L",
"nimac" : false,
"numImages" : 5,
"site" : "bookshare",
"titleAccessAlerts" : null,
"owner" : null,
"assignedBy" : "Org Member",
"dateAdded" : "2019-01-01T00:00:00Z",
"dateDownloaded" : "2019-05-01T00:00:00Z",
"links" : [ {
"rel" : "self",
"href" : "https://api.bookshare.org/v2/titles/1041744"
}, {
"rel" : "download",
"href" : "https://api.bookshare.org/v2/titles/1041744/{format}"
}, {
"rel" : "coverimage",
"href" : "http://covers.bookshare.org/4538345.jpg"
}, {
"rel" : "thumbnail",
"href" : "http://covers.bookshare.org/4538345.jpg"
} ]
} ],
"authorFacets" : null,
"categoryFacets" : null,
"message" : null,
"links" : [ {
"rel" : "self",
"href" : "https://api.bookshare.org/v2/myAssignedTitles?api_key=abcdefg"
} ]
}Example Curl request
$ curl 'https://api.bookshare.org/v2/myAssignedTitles?api_key=abcdefg' -i -X GET2.1.2. Assign a title to an organization member
POST /v2/assignedTitles/{userIdentifier}
Description
As a sponsor or Membership Assistant, assign a specific title to a particular organization member.
Parameters
Path Parameters
| Name | Description | Required | Schema | Default |
|---|---|---|---|---|
userIdentifier |
The unique identifying username or userAccountId of the user. |
X |
String |
null |
Form Parameters
| Name | Description | Required | Schema | Default |
|---|---|---|---|---|
bookshareId |
The title identifier of the book to assign. |
X |
String |
null |
Responses
| HTTP Code | Message | Datatype |
|---|---|---|
200 |
Assigned Title metadata collection response. |
|
0 |
Unexpected error |
Example HTTP request
POST /v2/assignedTitles/AP5xvS9bztz6ybiqkSIXp7VQQZPihRGp1Y1pVYTTaVXg2dpVrzDsNm5Q3uRxGS7Pl929nBh58YBD HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: api.bookshare.org
Content-Length: 35
bookshareId=1041744&api_key=abcdefgExample HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 2811
{
"limit" : 10,
"next" : null,
"totalResults" : 1,
"allows" : null,
"titles" : [ {
"allows" : null,
"bookshareId" : 1041744,
"title" : "The Adventures of Tom Sawyer",
"subtitle" : null,
"authors" : [ {
"firstName" : "Mark",
"lastName" : "Twain",
"middle" : null,
"prefix" : null,
"suffix" : null,
"links" : [ ]
} ],
"isbn13" : "9781551998121",
"synopsis" : "The classic boy-hero of American literature.",
"seriesTitle" : null,
"seriesNumber" : null,
"copyrightDate" : null,
"publishDate" : "2015-05-08T00:00:00Z",
"formats" : [ {
"formatId" : "DAISY",
"name" : "DAISY"
}, {
"formatId" : "BRF",
"name" : "BRF"
}, {
"formatId" : "DAISY_AUDIO",
"name" : "Audio"
}, {
"formatId" : "EPUB3",
"name" : "EPUB 3"
} ],
"externalFormats" : [ ],
"titleContentType" : "text",
"available" : true,
"contributors" : [ {
"name" : {
"displayName" : "Mark Twain",
"indexName" : "Twain, Mark",
"links" : [ ]
},
"type" : "author"
} ],
"composers" : null,
"lyricists" : null,
"arrangers" : null,
"translators" : null,
"editors" : null,
"instruments" : null,
"vocalParts" : null,
"languages" : [ "eng" ],
"contentWarnings" : [ ],
"categories" : [ {
"name" : "Literature and Fiction",
"description" : "Literature and Fiction",
"categoryType" : "Bookshare",
"code" : null,
"links" : [ ]
}, {
"name" : "FICTION / Action & Adventure",
"description" : "FICTION / Action & Adventure",
"categoryType" : "BISAC",
"code" : "FIC002000",
"links" : [ ]
} ],
"readingAgeMinimum" : 10,
"readingAgeMaximum" : 16,
"lexileCode" : "HL",
"lexileNumber" : "750L",
"nimac" : false,
"numImages" : 5,
"site" : "bookshare",
"titleAccessAlerts" : null,
"owner" : null,
"assignedBy" : "Org Sponsor",
"dateAdded" : "2019-01-01T00:00:00Z",
"dateDownloaded" : "2019-05-01T00:00:00Z",
"links" : [ {
"rel" : "self",
"href" : "https://api.bookshare.org/v2/titles/1041744"
}, {
"rel" : "download",
"href" : "https://api.bookshare.org/v2/titles/1041744/{format}?forUser={userAccountId}"
}, {
"rel" : "coverimage",
"href" : "http://covers.bookshare.org/4538345.jpg"
}, {
"rel" : "thumbnail",
"href" : "http://covers.bookshare.org/4538345.jpg"
} ]
} ],
"authorFacets" : null,
"categoryFacets" : null,
"message" : null,
"links" : [ {
"rel" : "self",
"href" : "https://api.bookshare.org/v2/assignedTitles/AP5xvS9bztz6ybiqkSIXp7VQQZPihRGp1Y1pVYTTaVXg2dpVrzDsNm5Q3uRxGS7Pl929nBh58YBD?api_key=abcdefg"
} ]
}Example Curl request
$ curl 'https://api.bookshare.org/v2/assignedTitles/AP5xvS9bztz6ybiqkSIXp7VQQZPihRGp1Y1pVYTTaVXg2dpVrzDsNm5Q3uRxGS7Pl929nBh58YBD' -i -X POST \
-d 'bookshareId=1041744&api_key=abcdefg'2.1.3. Un-assign a title for an organization member
DELETE /v2/assignedTitles/{userIdentifier}/{bookshareId}
Description
As a sponsor or Membership Assistant, un-assign a specific title for a particular organization member.
Parameters
Path Parameters
| Name | Description | Required | Schema | Default |
|---|---|---|---|---|
userIdentifier |
The unique identifying username or userAccountId of the user. |
X |
String |
null |
bookshareId |
The title identifier of the book to un-assign. |
X |
String |
null |
Responses
| HTTP Code | Message | Datatype |
|---|---|---|
200 |
Assigned Title metadata collection response. |
|
0 |
Unexpected error |
Example HTTP request
DELETE /v2/assignedTitles/AP5xvS9bztz6ybiqkSIXp7VQQZPihRGp1Y1pVYTTaVXg2dpVrzDsNm5Q3uRxGS7Pl929nBh58YBD/1041744 HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: api.bookshare.org
Content-Length: 15
api_key=abcdefgExample HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 361
{
"limit" : 10,
"next" : null,
"totalResults" : 0,
"allows" : null,
"titles" : [ ],
"authorFacets" : null,
"categoryFacets" : null,
"message" : null,
"links" : [ {
"rel" : "self",
"href" : "https://api.bookshare.org/v2/assignedTitles/AP5xvS9bztz6ybiqkSIXp7VQQZPihRGp1Y1pVYTTaVXg2dpVrzDsNm5Q3uRxGS7Pl929nBh58YBD?api_key=abcdefg"
} ]
}Example Curl request
$ curl 'https://api.bookshare.org/v2/assignedTitles/AP5xvS9bztz6ybiqkSIXp7VQQZPihRGp1Y1pVYTTaVXg2dpVrzDsNm5Q3uRxGS7Pl929nBh58YBD/1041744' -i -X DELETE \
-d 'api_key=abcdefg'2.1.4. Get titles assigned to an organization member
GET /v2/assignedTitles/{userIdentifier}
Description
As a sponsor or Membership Assistant, get a list of titles that have been assigned to a particular organization member.
Parameters
Path Parameters
| Name | Description | Required | Schema | Default |
|---|---|---|---|---|
userIdentifier |
The unique identifying username or userAccountId of the user. |
X |
String |
null |
Query Parameters
| Name | Description | Required | Schema | Default |
|---|---|---|---|---|
start |
If null or empty, it means to start at the beginning of the result set. Otherwise, it should be the value of 'next' that was returned from the previous request. |
- |
String |
null |
limit |
Maximum number of results to include. The maximum allowed is 100. |
- |
Integer |
10 |
sortOrder |
Primary sorting field. |
- |
enum [title, author, assignedBy, assignedDate, downloadDate] |
[title] |
direction |
Direction for sorting. |
- |
enum [asc, desc] |
[asc] |
Responses
| HTTP Code | Message | Datatype |
|---|---|---|
200 |
Assigned Title metadata collection response. |
|
0 |
Unexpected error |
Example HTTP request
GET /v2/assignedTitles/AP5xvS9bztz6ybiqkSIXp7VQQZPihRGp1Y1pVYTTaVXg2dpVrzDsNm5Q3uRxGS7Pl929nBh58YBD?api_key=abcdefg HTTP/1.1
Host: api.bookshare.orgExample HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 2811
{
"limit" : 10,
"next" : null,
"totalResults" : 1,
"allows" : null,
"titles" : [ {
"allows" : null,
"bookshareId" : 1041744,
"title" : "The Adventures of Tom Sawyer",
"subtitle" : null,
"authors" : [ {
"firstName" : "Mark",
"lastName" : "Twain",
"middle" : null,
"prefix" : null,
"suffix" : null,
"links" : [ ]
} ],
"isbn13" : "9781551998121",
"synopsis" : "The classic boy-hero of American literature.",
"seriesTitle" : null,
"seriesNumber" : null,
"copyrightDate" : null,
"publishDate" : "2015-05-08T00:00:00Z",
"formats" : [ {
"formatId" : "DAISY",
"name" : "DAISY"
}, {
"formatId" : "BRF",
"name" : "BRF"
}, {
"formatId" : "DAISY_AUDIO",
"name" : "Audio"
}, {
"formatId" : "EPUB3",
"name" : "EPUB 3"
} ],
"externalFormats" : [ ],
"titleContentType" : "text",
"available" : true,
"contributors" : [ {
"name" : {
"displayName" : "Mark Twain",
"indexName" : "Twain, Mark",
"links" : [ ]
},
"type" : "author"
} ],
"composers" : null,
"lyricists" : null,
"arrangers" : null,
"translators" : null,
"editors" : null,
"instruments" : null,
"vocalParts" : null,
"languages" : [ "eng" ],
"contentWarnings" : [ ],
"categories" : [ {
"name" : "Literature and Fiction",
"description" : "Literature and Fiction",
"categoryType" : "Bookshare",
"code" : null,
"links" : [ ]
}, {
"name" : "FICTION / Action & Adventure",
"description" : "FICTION / Action & Adventure",
"categoryType" : "BISAC",
"code" : "FIC002000",
"links" : [ ]
} ],
"readingAgeMinimum" : 10,
"readingAgeMaximum" : 16,
"lexileCode" : "HL",
"lexileNumber" : "750L",
"nimac" : false,
"numImages" : 5,
"site" : "bookshare",
"titleAccessAlerts" : null,
"owner" : null,
"assignedBy" : "Org Sponsor",
"dateAdded" : "2019-01-01T00:00:00Z",
"dateDownloaded" : "2019-05-01T00:00:00Z",
"links" : [ {
"rel" : "self",
"href" : "https://api.bookshare.org/v2/titles/1041744"
}, {
"rel" : "download",
"href" : "https://api.bookshare.org/v2/titles/1041744/{format}?forUser={userAccountId}"
}, {
"rel" : "coverimage",
"href" : "http://covers.bookshare.org/4538345.jpg"
}, {
"rel" : "thumbnail",
"href" : "http://covers.bookshare.org/4538345.jpg"
} ]
} ],
"authorFacets" : null,
"categoryFacets" : null,
"message" : null,
"links" : [ {
"rel" : "self",
"href" : "https://api.bookshare.org/v2/assignedTitles/AP5xvS9bztz6ybiqkSIXp7VQQZPihRGp1Y1pVYTTaVXg2dpVrzDsNm5Q3uRxGS7Pl929nBh58YBD?api_key=abcdefg"
} ]
}Example Curl request
$ curl 'https://api.bookshare.org/v2/assignedTitles/AP5xvS9bztz6ybiqkSIXp7VQQZPihRGp1Y1pVYTTaVXg2dpVrzDsNm5Q3uRxGS7Pl929nBh58YBD?api_key=abcdefg' -i -X GET2.2. Bookmarks
A bookmark represents a location in a title that a user wants to save. Users are able to place and remove bookmarks on any title that they can access. Bookmarks are specific for a format, so the set of bookmarks a user creates when reading an EPUB3 version of a title will be different than any bookmarks they create when reading a DAISY version of the title.
2.2.1. Delete a bookmark for a title
DELETE /v2/myBookmarks
Description
Delete a bookmark made by the current user on the given title and format at the given location.
Parameters
Query Parameters
| Name | Description | Required | Schema | Default |
|---|---|---|---|---|
bookshareId |
The title identifier of the content being read. |
X |
String |
null |
location |
The format-specific location identifier to signify the bookmark’s location. For example, the EPUB3 format may use EPUB Canonical Fragment Identifiers. |
X |
String |
null |
format |
The format of the title where the bookmark was made. |
- |
enum [DAISY, DAISY_AUDIO, DAISY_2_AUDIO, BRF, EPUB3, PDF, DOCX] |
[EPUB3] |
Responses
| HTTP Code | Message | Datatype |
|---|---|---|
200 |
Bookmarks collection |
|
0 |
Unexpected error |
Example HTTP request
DELETE /v2/myBookmarks?bookshareId=101175&location=book.epubcfi(/6/4%5Bitemref_2%5D!/4/2%5Blevel1_000000%5D/8%5Blevel2_000003%5D/34%5Bp_000309%5D/1:0) HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: api.bookshare.org
Content-Length: 15
api_key=abcdefgExample HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 556
{
"limit" : 10,
"next" : "abcde",
"totalResults" : 0,
"allows" : [ "POST" ],
"bookmarks" : [ ],
"links" : [ {
"rel" : "self",
"href" : "https://api.bookshare.org/v2/myBookmarks?bookshareId=101175&location=book.epubcfi(/6/4[itemref_2]!/4/2[level1_000000]/8[level2_000003]/34[p_000309]/1:0)&api_key=abcdefg"
}, {
"rel" : "next",
"href" : "https://api.bookshare.org/v2/myBookmarks?start=abcde&location=book.epubcfi(/6/4[itemref_2]!/4/2[level1_000000]/8[level2_000003]/34[p_000309]/1:0)&api_key=abcdefg&bookshareId=101175"
} ]
}Example Curl request
$ curl 'https://api.bookshare.org/v2/myBookmarks?bookshareId=101175&location=book.epubcfi(/6/4%5Bitemref_2%5D!/4/2%5Blevel1_000000%5D/8%5Blevel2_000003%5D/34%5Bp_000309%5D/1:0)' -i -X DELETE \
-d 'api_key=abcdefg'2.2.2. Get bookmarks for a title
GET /v2/myBookmarks
Description
Get the bookmarks made by the current user on the given title and format.
Parameters
Query Parameters
| Name | Description | Required | Schema | Default |
|---|---|---|---|---|
bookshareId |
The title identifier of the content being read. |
X |
String |
null |
format |
The format of the title where the bookmark was made. |
- |
enum [DAISY, DAISY_AUDIO, DAISY_2_AUDIO, BRF, EPUB3, PDF, DOCX] |
[EPUB3] |
start |
If null or empty, it means to start at the beginning of the result set. Otherwise, it should be the value of 'next' that was returned from the previous request. |
- |
String |
null |
limit |
Maximum number of results to include. The maximum allowed is 100. |
- |
Integer |
10 |
Responses
| HTTP Code | Message | Datatype |
|---|---|---|
200 |
Bookmarks collection |
|
0 |
Unexpected error |
Example HTTP request
GET /v2/myBookmarks?bookshareId=101175&api_key=abcdefg HTTP/1.1
Host: api.bookshare.orgExample HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 1003
{
"limit" : 10,
"next" : "abcde",
"totalResults" : 1,
"allows" : [ "POST" ],
"bookmarks" : [ {
"allows" : [ "DELETE" ],
"bookshareId" : "101175",
"format" : {
"formatId" : "EPUB3",
"name" : "EPUB 3"
},
"location" : "book.epubcfi(/6/4[itemref_2]!/4/2[level1_000000]/8[level2_000003]/34[p_000309]/1:0)",
"text" : "In the night a strange noise...",
"dateCreated" : null,
"position" : null,
"progression" : null,
"totalProgression" : null,
"links" : [ {
"rel" : "self",
"href" : "https://api.bookshare.org/v2/myBookmarks?api_key=abcdefg&bookshareId=101175&location=book.epubcfi(/6/4[itemref_2]!/4/2[level1_000000]/8[level2_000003]/34[p_000309]/1:0)"
} ]
} ],
"links" : [ {
"rel" : "self",
"href" : "https://api.bookshare.org/v2/myBookmarks?bookshareId=101175&api_key=abcdefg"
}, {
"rel" : "next",
"href" : "https://api.bookshare.org/v2/myBookmarks?start=abcde&api_key=abcdefg&bookshareId=101175"
} ]
}Example Curl request
$ curl 'https://api.bookshare.org/v2/myBookmarks?bookshareId=101175&api_key=abcdefg' -i -X GET2.2.3. Submit a bookmark
POST /v2/myBookmarks
Description
Submit a new or updated bookmark to save a location within a title.
Parameters
Form Parameters
| Name | Description | Required | Schema | Default |
|---|---|---|---|---|
bookshareId |
Unique identifier of the title. |
X |
String |
null |
location |
The format-specific location identifier to signify the bookmark’s location. For example, the EPUB3 format may use EPUB Canonical Fragment Identifiers. |
X |
String |
null |
format |
The format of the title where the bookmark is being added. |
- |
enum [DAISY, DAISY_AUDIO, DAISY_2_AUDIO, BRF, EPUB3, PDF, DOCX] |
[EPUB3] |
text |
The text at the location of the bookmark. |
- |
String |
null |
position |
The index of the current section where the bookmark resides within the publication spine. |
- |
Integer |
null |
progression |
The percent progress within the current section at the location of the bookmark. |
- |
Double |
null |
totalProgression |
The percent progress within the whole title at the location of the bookmark. |
- |
Double |
null |
Example HTTP request
POST /v2/myBookmarks HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: api.bookshare.org
Content-Length: 264
bookshareId=101175&location=book.epubcfi%28%2F6%2F4%5Bitemref_2%5D%21%2F4%2F2%5Blevel1_000000%5D%2F8%5Blevel2_000003%5D%2F34%5Bp_000309%5D%2F1%3A0%29&format=EPUB3&text=In+the+night+a+strange+noise...&position=1&progression=0.2&totalProgression=0.75&api_key=abcdefgExample HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 78
{
"key" : "SUCCESS",
"messages" : [ "Bookmark submitted successfully." ]
}Example Curl request
$ curl 'https://api.bookshare.org/v2/myBookmarks' -i -X POST \
-d 'bookshareId=101175&location=book.epubcfi%28%2F6%2F4%5Bitemref_2%5D%21%2F4%2F2%5Blevel1_000000%5D%2F8%5Blevel2_000003%5D%2F34%5Bp_000309%5D%2F1%3A0%29&format=EPUB3&text=In+the+night+a+strange+noise...&position=1&progression=0.2&totalProgression=0.75&api_key=abcdefg'2.3. Documents
2.3.1. Create a document
POST /v2/myDocuments
Description
Upload a new file.
Parameters
Form Parameters
| Name | Description | Required | Schema | Default |
|---|---|---|---|---|
name |
The document’s name. |
X |
String |
null |
googleDriveFileId |
The unique file identifier for the Google Drive file. Required if the file comes from Google Drive. |
- |
String |
null |
mimeType |
The MIME type of the file being uploaded |
X |
enum [application/pdf, image/jpeg, image/heif] |
null |
Responses
| HTTP Code | Message | Datatype |
|---|---|---|
202 |
Request has been received, and will be processed. |
|
0 |
Unexpected error |
Example HTTP request
POST /v2/myDocuments HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: api.bookshare.org
Content-Length: 83
name=NewDocument&googleDriveFileId=12345&mimeType=application%2Fpdf&api_key=abcdefgExample HTTP response
HTTP/1.1 202 Accepted
Content-Type: application/json
Content-Length: 91
{
"key" : "SUBMITTED",
"messages" : [ "Document NewDocument submitted successfully" ]
}Example Curl request
$ curl 'https://api.bookshare.org/v2/myDocuments' -i -X POST \
-d 'name=NewDocument&googleDriveFileId=12345&mimeType=application%2Fpdf&api_key=abcdefg'2.3.2. Get my documents
GET /v2/myDocuments
Description
Request a list of the documents uploaded by the authenticated user making the request.
Parameters
Query Parameters
| Name | Description | Required | Schema | Default |
|---|---|---|---|---|
keyword |
Search string to use in searching for document names. |
- |
String |
null |
limit |
Maximum number of results to include. The maximum allowed is 100. |
- |
Integer |
10 |
sortOrder |
Primary sorting field. |
- |
enum [title, dateUploaded] |
[dateUploaded] |
direction |
Direction for sorting. |
- |
enum [asc, desc] |
[desc] |
start |
If null or empty, it means to start at the beginning of the result set. Otherwise, it should be the value of 'next' that was returned from the previous request. |
- |
String |
null |
Responses
| HTTP Code | Message | Datatype |
|---|---|---|
200 |
Title metadata collection response. |
|
0 |
Unexpected error |
Example HTTP request
GET /v2/myDocuments?api_key=abcdefg HTTP/1.1
Host: api.bookshare.orgExample HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 1834
{
"limit" : 10,
"next" : null,
"totalResults" : 1,
"allows" : null,
"titles" : [ {
"allows" : null,
"bookshareId" : 2713986,
"title" : "Example Document",
"subtitle" : null,
"authors" : null,
"isbn13" : null,
"synopsis" : null,
"seriesTitle" : null,
"seriesNumber" : null,
"copyrightDate" : "1970",
"publishDate" : null,
"formats" : [ {
"formatId" : "DAISY",
"name" : "DAISY"
}, {
"formatId" : "BRF",
"name" : "BRF"
}, {
"formatId" : "DAISY_AUDIO",
"name" : "Audio"
}, {
"formatId" : "EPUB3",
"name" : "EPUB 3"
} ],
"externalFormats" : [ ],
"titleContentType" : "",
"available" : true,
"contributors" : null,
"composers" : null,
"lyricists" : null,
"arrangers" : null,
"translators" : null,
"editors" : null,
"instruments" : null,
"vocalParts" : null,
"languages" : [ "eng" ],
"contentWarnings" : null,
"categories" : [ ],
"readingAgeMinimum" : null,
"readingAgeMaximum" : null,
"lexileCode" : null,
"lexileNumber" : null,
"nimac" : false,
"numImages" : null,
"site" : "",
"titleAccessAlerts" : null,
"owner" : "John Smith",
"links" : [ {
"rel" : "self",
"href" : "https://api.bookshare.org/v2/titles/2713986"
}, {
"rel" : "download",
"href" : "https://api.bookshare.org/v2/titles/2713986/{format}"
}, {
"rel" : "coverimage",
"href" : "http://covers.bookshare.org/4538345.jpg"
}, {
"rel" : "thumbnail",
"href" : "http://covers.bookshare.org/4538345.jpg"
} ]
} ],
"authorFacets" : null,
"categoryFacets" : null,
"message" : null,
"links" : [ {
"rel" : "self",
"href" : "https://api.bookshare.org/v2/myDocuments?api_key=abcdefg"
} ]
}Example Curl request
$ curl 'https://api.bookshare.org/v2/myDocuments?api_key=abcdefg' -i -X GET2.4. Highlights
A highlight represents a selection of text at a location in a title that a user wants to save. Users are able to create, update, and remove highlights on titles they can access. Highlights are specific for a format, so the set of highlights a user creates when reading an EPUB3 version of a title will be different than any highlights they create when reading a DAISY version of the title.
2.4.1. Delete a highlight
DELETE /v2/myHighlights
Description
Deletes a highlight made by the user for a title in a given format.
Parameters
Query Parameters
| Name | Description | Required | Schema | Default |
|---|---|---|---|---|
bookshareId |
The title identifier of the content being read. |
X |
String |
null |
startLocation |
The format-specific location identifier to signify the highlight’s start location. For example, the EPUB3 format may use EPUB Canonical Fragment Identifiers. |
X |
String |
null |
endLocation |
The format-specific end location identifier to signify the highlight’s end location. For example, the EPUB3 format may use EPUB Canonical Fragment Identifiers. |
X |
String |
null |
format |
The format of the title where the highlight was made. |
- |
enum [DAISY, DAISY_AUDIO, DAISY_2_AUDIO, BRF, EPUB3, PDF, DOCX] |
[EPUB3] |
Responses
| HTTP Code | Message | Datatype |
|---|---|---|
200 |
Highlights collection |
|
0 |
Unexpected error |
Example HTTP request
DELETE /v2/myHighlights?bookshareId=101175&format=EPUB3&startLocation=epubcfi(/6/42!/4/2/12/1:282)&endLocation=epubcfi(/6/42!/4/2/12/1:340) HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: api.bookshare.org
Content-Length: 15
api_key=abcdefgExample HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 1043
{
"limit" : 10,
"next" : "abcde",
"allows" : [ "POST" ],
"highlights" : [ {
"allows" : [ "PUT", "DELETE" ],
"bookshareId" : "101175",
"format" : {
"formatId" : "EPUB3",
"name" : "EPUB 3"
},
"startLocation" : "epubcfi(/6/30!/4/2/12/1:0)",
"endLocation" : "epubcfi(/6/30!/4/2/12/1:107)",
"highlightText" : "When his camera was ruined and McCandless stopped taking photographs...",
"color" : "#ff787f",
"annotationNote" : "My first highlight!",
"dateUpdated" : "2023-01-01T00:00:00Z",
"startPosition" : null,
"startProgression" : null,
"startTotalProgression" : null,
"endPosition" : null,
"endProgression" : null,
"endTotalProgression" : null,
"links" : [ ]
} ],
"links" : [ {
"rel" : "self",
"href" : "https://api.bookshare.org/v2/myHighlights?bookshareId=101175&format=EPUB3&api_key=abcdefg"
}, {
"rel" : "next",
"href" : "https://api.bookshare.org/v2/myHighlights?format=EPUB3&start=abcde&api_key=abcdefg&bookshareId=101175"
} ]
}Example Curl request
$ curl 'https://api.bookshare.org/v2/myHighlights?bookshareId=101175&format=EPUB3&startLocation=epubcfi(/6/42!/4/2/12/1:282)&endLocation=epubcfi(/6/42!/4/2/12/1:340)' -i -X DELETE \
-d 'api_key=abcdefg'2.4.2. Get highlights for a title
GET /v2/myHighlights
Description
Get the highlights a user has made in a title of the given format.
Parameters
Query Parameters
| Name | Description | Required | Schema | Default |
|---|---|---|---|---|
bookshareId |
The title identifier of the content being read. |
X |
String |
null |
format |
The format of the title where the highlight was made. |
- |
enum [DAISY, DAISY_AUDIO, DAISY_2_AUDIO, BRF, EPUB3, PDF, DOCX] |
[EPUB3] |
start |
If null or empty, it means to start at the beginning of the result set. Otherwise, it should be the value of 'next' that was returned from the previous request. |
- |
String |
null |
limit |
Maximum number of results to include. The maximum allowed is 100. |
- |
Integer |
10 |
Responses
| HTTP Code | Message | Datatype |
|---|---|---|
200 |
Highlights collection |
|
0 |
Unexpected error |
Example HTTP request
GET /v2/myHighlights?bookshareId=101175&format=EPUB3&api_key=abcdefg HTTP/1.1
Host: api.bookshare.orgExample HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 1102
{
"limit" : 10,
"next" : "abcde",
"allows" : [ "POST" ],
"highlights" : [ {
"allows" : [ "PUT", "DELETE" ],
"bookshareId" : "101175",
"format" : {
"formatId" : "EPUB3",
"name" : "EPUB 3"
},
"startLocation" : "epubcfi(/6/18[itemref_9]!/4/2[ch005]/4[p_000854]/1:0)",
"endLocation" : "epubcfi(/6/18[itemref_9]!/4/2[ch005]/4[p_000854]/1:239)",
"highlightText" : "When I glance over my notes and records of the Sherlock Holmes...",
"color" : "#FFA500",
"annotationNote" : "Highlighting this for later...",
"dateUpdated" : "2023-01-01T00:00:00Z",
"startPosition" : null,
"startProgression" : null,
"startTotalProgression" : null,
"endPosition" : null,
"endProgression" : null,
"endTotalProgression" : null,
"links" : [ ]
} ],
"links" : [ {
"rel" : "self",
"href" : "https://api.bookshare.org/v2/myHighlights?bookshareId=101175&format=EPUB3&api_key=abcdefg"
}, {
"rel" : "next",
"href" : "https://api.bookshare.org/v2/myHighlights?format=EPUB3&start=abcde&api_key=abcdefg&bookshareId=101175"
} ]
}Example Curl request
$ curl 'https://api.bookshare.org/v2/myHighlights?bookshareId=101175&format=EPUB3&api_key=abcdefg' -i -X GET2.4.3. Create a highlight
POST /v2/myHighlights
Description
Create a new highlight within a title of a specific format.
Parameters
Form Parameters
| Name | Description | Required | Schema | Default |
|---|---|---|---|---|
bookshareId |
Unique identifier of the title. |
X |
String |
null |
startLocation |
The format-specific location identifier to signify the highlight’s start location. For example, the EPUB3 format may use EPUB Canonical Fragment Identifiers. |
X |
String |
null |
endLocation |
The format-specific end location identifier to signify the highlight’s end location. For example, the EPUB3 format may use EPUB Canonical Fragment Identifiers. |
X |
String |
null |
format |
The format of the title where the highlight is being added. |
- |
enum [DAISY, DAISY_AUDIO, DAISY_2_AUDIO, BRF, EPUB3, PDF, DOCX] |
[EPUB3] |
highlightText |
The text at the location of the highlight. |
X |
String |
null |
annotationNote |
A string that a user can include alongside a highlight. |
- |
String |
null |
color |
The hexadecimal color code of the highlight |
X |
String |
null |
startPosition |
The start index of the current section where the highlight resides within the publication spine. |
- |
Integer |
null |
startProgression |
The percent progress within the current section at the start location of the highlight. |
- |
Double |
null |
startTotalProgression |
The percent progress within the whole title at the start location of the highlight. |
- |
Double |
null |
endPosition |
The end index of the current section where the highlight resides within the publication spine. |
- |
Integer |
null |
endProgression |
The percent progress within the current section at the end location of the highlight. |
- |
Double |
null |
endTotalProgression |
The percent progress within the whole title at the end location of the highlight. |
- |
Double |
null |
Example HTTP request
POST /v2/myHighlights HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: api.bookshare.org
Content-Length: 536
bookshareId=101175&startLocation=epubcfi%28%2F6%2F4%5Bitemref_2%5D%21%2F4%2F2%5Blevel1_000000%5D%2F10%5Blevel2_000004%5D%2F132%5Bp_000434%5D%2F1%3A0%29&endLocation=epubcfi%28%2F6%2F4%5Bitemref_2%5D%21%2F4%2F2%5Blevel1_000000%5D%2F10%5Blevel2_000004%5D%2F134%5Bp_000435%5D%2F1%3A0%29&format=EPUB3&highlightText=Harry%E2%80%94yer+a+wizard.&color=%23f0fc03&annotationNote=Want+to+save+this+for+later%21&startPosition=1&startProgression=0.1&startTotalProgression=0.05&endPosition=1&endProgression=0.2&endTotalProgression=0.1&api_key=abcdefgExample HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 79
{
"key" : "SUCCESS",
"messages" : [ "Highlight submitted successfully." ]
}Example Curl request
$ curl 'https://api.bookshare.org/v2/myHighlights' -i -X POST \
-d 'bookshareId=101175&startLocation=epubcfi%28%2F6%2F4%5Bitemref_2%5D%21%2F4%2F2%5Blevel1_000000%5D%2F10%5Blevel2_000004%5D%2F132%5Bp_000434%5D%2F1%3A0%29&endLocation=epubcfi%28%2F6%2F4%5Bitemref_2%5D%21%2F4%2F2%5Blevel1_000000%5D%2F10%5Blevel2_000004%5D%2F134%5Bp_000435%5D%2F1%3A0%29&format=EPUB3&highlightText=Harry%E2%80%94yer+a+wizard.&color=%23f0fc03&annotationNote=Want+to+save+this+for+later%21&startPosition=1&startProgression=0.1&startTotalProgression=0.05&endPosition=1&endProgression=0.2&endTotalProgression=0.1&api_key=abcdefg'2.4.4. Update a highlight
PUT /v2/myHighlights
Description
Update the annotation note or color of a highlight within a title of a specific format.
Parameters
Form Parameters
| Name | Description | Required | Schema | Default |
|---|---|---|---|---|
bookshareId |
Unique identifier of the title. |
X |
String |
null |
startLocation |
The format-specific location identifier to signify the highlight’s start location. For example, the EPUB3 format may use EPUB Canonical Fragment Identifiers. |
X |
String |
null |
endLocation |
The format-specific end location identifier to signify the highlight’s end location. For example, the EPUB3 format may use EPUB Canonical Fragment Identifiers. |
X |
String |
null |
format |
The format of the title where the highlight is being added. |
- |
enum [DAISY, DAISY_AUDIO, DAISY_2_AUDIO, BRF, EPUB3, PDF, DOCX] |
[EPUB3] |
annotationNote |
A string that a user can include alongside a highlight. |
- |
String |
null |
color |
The hexadecimal color code of the highlight |
- |
String |
null |
Example HTTP request
PUT /v2/myHighlights HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: api.bookshare.org
Content-Length: 364
bookshareId=101175&startLocation=epubcfi%28%2F6%2F4%5Bitemref_2%5D%21%2F4%2F2%5Blevel1_000000%5D%2F4%5Blevel2_000000%5D%2F10%5Bp_000003%5D%2F1%3A0%29&endLocation=epubcfi%28%2F6%2F4%5Bitemref_2%5D%21%2F4%2F2%5Blevel1_000000%5D%2F4%5Blevel2_000000%5D%2F10%5Bp_000003%5D%2F1%3A130%29&format=EPUB3&annotationNote=Updating+this+highlight&color=%23f0fc03&api_key=abcdefgExample HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 77
{
"key" : "SUCCESS",
"messages" : [ "Highlight updated successfully." ]
}Example Curl request
$ curl 'https://api.bookshare.org/v2/myHighlights' -i -X PUT \
-d 'bookshareId=101175&startLocation=epubcfi%28%2F6%2F4%5Bitemref_2%5D%21%2F4%2F2%5Blevel1_000000%5D%2F4%5Blevel2_000000%5D%2F10%5Bp_000003%5D%2F1%3A0%29&endLocation=epubcfi%28%2F6%2F4%5Bitemref_2%5D%21%2F4%2F2%5Blevel1_000000%5D%2F4%5Blevel2_000000%5D%2F10%5Bp_000003%5D%2F1%3A130%29&format=EPUB3&annotationNote=Updating+this+highlight&color=%23f0fc03&api_key=abcdefg'2.5. Organization
An organization represents a collection of users, either sponsors or members. These might be schools, libraries or other organizations that work on behalf of qualified individuals. Members of an organization are sometimes restricted in what actions they can perform, with sponsors acting on their behalf to do things like download titles. Sponsors have some limited administrative abilities in their organizations, to add, update and remove individual members.
2.5.1. Create a member for my organization
POST /v2/myOrganization/members
Description
Create a new user account for a member of my organization, with the properties provided.
Parameters
Form Parameters
| Name | Description | Required | Schema | Default |
|---|---|---|---|---|
firstName |
The user’s first name. |
X |
String |
null |
lastName |
The user’s last name. |
X |
String |
null |
dateOfBirth |
The user’s date of birth. The value should be formatted as 'YYYY-MM-DD'. |
X |
String |
null |
grade |
User’s current grade. Values are from ONIX codelist 77 for US grades, BIC for UK grades |
X |
String |
null |
username |
Username for the user. |
- |
String |
null |
password |
The user’s password. It must be from 8-32 characters long, and contain at least one letter and one number. |
- |
String |
null |
disabilityType |
The types of disabilities involved. Enter each disability type as a separate instance of this parameter. |
- |
enum [visual, learning, physical, nonspecific] |
null |
disabilityPlan |
The disability plan for the user. Enter each disability plan as a separate instance of this parameter. |
- |
enum [iep, section504] |
null |
onQuickList |
True if the user should be added to the quicklist of the sponsor making the request. |
- |
Boolean |
null |
Responses
| HTTP Code | Message | Datatype |
|---|---|---|
201 |
Member Summary response |
|
0 |
Unexpected error |
Example HTTP request
POST /v2/myOrganization/members HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: api.bookshare.org
Content-Length: 181
firstName=Org&lastName=Member&dateOfBirth=2015-07-15&grade=6&username=OM_userName&disabilityType=learning&disabilityType=visual&disabilityPlan=iep&password=testpass1&api_key=abcdefgExample HTTP response
HTTP/1.1 201 Created
Location: https://api.bookshare.org/v2/myOrganization/members/AP5xvS9bztz6ybiqkSIXp7VQQZPihRGp1Y1pVYTTaVXg2dpVrzDsNm5Q3uRxGS7Pl929nBh58YBD
Content-Type: application/json
Content-Length: 952
{
"allows" : [ "PUT" ],
"userAccountId" : "AP5xvS9bztz6ybiqkSIXp7VQQZPihRGp1Y1pVYTTaVXg2dpVrzDsNm5Q3uRxGS7Pl929nBh58YBD",
"userName" : "OM_userName",
"name" : {
"firstName" : "Org",
"lastName" : "Member",
"middle" : null,
"prefix" : null,
"suffix" : null,
"links" : [ ]
},
"emailAddress" : null,
"grade" : "6",
"dateOfBirth" : "2015-07-15",
"disabilities" : [ "learning", "visual" ],
"plans" : [ "iep" ],
"roles" : [ "organizationMember" ],
"onQuickList" : false,
"preferredFormat" : {
"formatId" : "DAISY",
"name" : "DAISY"
},
"allowAdultContent" : false,
"phoneNumber" : null,
"language" : "eng",
"hasAgreement" : false,
"locked" : false,
"canDownload" : true,
"sponsorManageable" : true,
"links" : [ {
"rel" : "self",
"href" : "https://api.bookshare.org/v2/myOrganization/members/AP5xvS9bztz6ybiqkSIXp7VQQZPihRGp1Y1pVYTTaVXg2dpVrzDsNm5Q3uRxGS7Pl929nBh58YBD"
} ]
}Example Curl request
$ curl 'https://api.bookshare.org/v2/myOrganization/members' -i -X POST \
-d 'firstName=Org&lastName=Member&dateOfBirth=2015-07-15&grade=6&username=OM_userName&disabilityType=learning&disabilityType=visual&disabilityPlan=iep&password=testpass1&api_key=abcdefg'2.5.2. Create an organization account and its primary contact account
POST /v2/myOrganization
Description
Create a new organization account and new user account for its primary contact. The information about an organization can either come from the individual form elements (name, address, etc) or by providing a reference organization identifier. Only available to anonymous users on certain API clients.
Parameters
Form Parameters
| Name | Description | Required | Schema | Default |
|---|---|---|---|---|
referenceOrgId |
Unique identifier of a matching reference organization. |
- |
String |
null |
organizationName |
The name of the organization. Required if referenceOrgId is not provided. |
- |
String |
null |
address1 |
The organization’s street address. |
- |
String |
null |
address2 |
Any extra street address information for the organization. |
- |
String |
null |
city |
The organization’s city. |
- |
String |
null |
state |
The organization’s state or province. The value should be either a two-character postal abbreviation or an ISO 3166-2 subdivision code for the user’s country. This field is only relevant for subdivisions of the US and Canada. |
- |
String |
null |
country |
The organization’s country. The values should be a two-character ISO 3166 alpha-2 country code. Required if referenceOrgId is not provided. |
- |
String |
null |
postalCode |
The organization’s postal code. |
- |
String |
null |
phoneNumber |
The organization’s phone number. |
- |
String |
null |
website |
The organization’s website. |
- |
String |
null |
organizationType |
Type of organization. List of possible values exists at /v2/organizationTypes. Required if referenceOrgId is not provided. |
- |
String |
null |
contactFirstName |
The primary contact’s first name. |
X |
String |
null |
contactLastName |
The primary contact’s last name. |
X |
String |
null |
contactPhoneNumber |
The primary contact’s phone number. |
- |
String |
null |
contactTitle |
The title of the primary contact. |
X |
String |
null |
contactEmailAddress |
The primary contact’s email address. |
X |
String |
null |
contactPassword |
The primary contact’s password. It must be from 8-32 characters long, and contain at least one letter and one number. |
X |
String |
null |
agreementSigned |
True if the user has signed the organizational membership agreement. |
X |
Boolean |
null |
Responses
| HTTP Code | Message | Datatype |
|---|---|---|
201 |
Organization summary response |
|
0 |
Unexpected error |
Example HTTP request
POST /v2/myOrganization HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: api.bookshare.org
Content-Length: 227
referenceOrgId=456&contactFirstName=John&contactLastName=Doe&contactTitle=Manager&contactPhoneNumber=789-123-456&contactEmailAddress=primarycontact%40exampleorg.com&contactPassword=testpass1&agreementSigned=true&api_key=abcdefgExample HTTP response
HTTP/1.1 201 Created
Content-Type: application/json
Content-Length: 897
{
"allows" : null,
"organizationName" : "Example organization",
"address" : {
"address1" : "123 Main Street",
"address2" : null,
"city" : "SmallTown",
"state" : "CA",
"country" : "US",
"postalCode" : "98765"
},
"phoneNumber" : "123-456-7890",
"webSite" : "exampleorg.com",
"organizationType" : "usPublicK12",
"primaryContact" : {
"allows" : null,
"userAccountId" : "AP5xvS9bztz6ybiqkSIXp7VQQZPihRGp1Y1pVYTTaVXg2dpVrzDsNm5Q3uRxGS7Pl929nBh58YBD",
"name" : {
"firstName" : "John",
"lastName" : "Doe",
"middle" : null,
"prefix" : null,
"suffix" : null,
"links" : [ ]
},
"emailAddress" : "primarycontact@exampleorg.com",
"phoneNumber" : "789-123-456",
"title" : "Manager",
"links" : [ ]
},
"links" : [ {
"rel" : "self",
"href" : "https://api.bookshare.org/v2/myOrganization"
} ]
}Example Curl request
$ curl 'https://api.bookshare.org/v2/myOrganization' -i -X POST \
-d 'referenceOrgId=456&contactFirstName=John&contactLastName=Doe&contactTitle=Manager&contactPhoneNumber=789-123-456&contactEmailAddress=primarycontact%40exampleorg.com&contactPassword=testpass1&agreementSigned=true&api_key=abcdefg'2.5.3. Create a sponsor for my organization
POST /v2/myOrganization/sponsors
Description
As a sponsor, create a new user account for a sponsor of my organization, with the properties provided.
Parameters
Form Parameters
| Name | Description | Required | Schema | Default |
|---|---|---|---|---|
firstName |
The sponsor’s first name. |
X |
String |
null |
lastName |
The sponsor’s last name. |
X |
String |
null |
phoneNumber |
The sponsor’s phone number. |
X |
String |
null |
emailAddress |
The sponsor’s email address. This value will also be used as the username. |
X |
String |
null |
title |
The sponsor’s job title. |
X |
String |
null |
Responses
| HTTP Code | Message | Datatype |
|---|---|---|
201 |
Sponsor Summary response |
|
0 |
Unexpected error |
Example HTTP request
POST /v2/myOrganization/sponsors HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: api.bookshare.org
Content-Length: 124
firstName=Org&lastName=Sponsor&phoneNumber=123-456-7890&emailAddress=sponsor%40school.org&title=SponsorTitle&api_key=abcdefgExample HTTP response
HTTP/1.1 201 Created
Location: https://api.bookshare.org/v2/myOrganization/sponsors/AP5xvS9bztz6ybiqkSIXp7VQQZPihRGp1Y1pVYTTaVXg2dpVrzDsNm5Q3uRxGS7Pl929nBh58YBD
Content-Type: application/json
Content-Length: 569
{
"allows" : [ "PUT" ],
"userAccountId" : "AP5xvS9bztz6ybiqkSIXp7VQQZPihRGp1Y1pVYTTaVXg2dpVrzDsNm5Q3uRxGS7Pl929nBh58YBD",
"name" : {
"firstName" : "Org",
"lastName" : "Sponsor",
"middle" : null,
"prefix" : null,
"suffix" : null,
"links" : [ ]
},
"emailAddress" : "sponsor@school.org",
"phoneNumber" : "123-456-7890",
"title" : "SponsorTitle",
"links" : [ {
"rel" : "self",
"href" : "https://api.bookshare.org/v2/myOrganization/sponsors/AP5xvS9bztz6ybiqkSIXp7VQQZPihRGp1Y1pVYTTaVXg2dpVrzDsNm5Q3uRxGS7Pl929nBh58YBD"
} ]
}Example Curl request
$ curl 'https://api.bookshare.org/v2/myOrganization/sponsors' -i -X POST \
-d 'firstName=Org&lastName=Sponsor&phoneNumber=123-456-7890&emailAddress=sponsor%40school.org&title=SponsorTitle&api_key=abcdefg'2.5.4. Get a list of members of my organization
GET /v2/myOrganization/members
Description
As a sponsor, get a list of members of my organization.
Parameters
Query Parameters
| Name | Description | Required | Schema | Default |
|---|---|---|---|---|
start |
If null or empty, it means to start at the beginning of the result set. Otherwise, it should be the value of 'next' that was returned from the previous request. |
- |
String |
null |
limit |
Maximum number of results to include. The maximum allowed is 100. |
- |
Integer |
10 |
sortOrder |
Primary sorting field. |
- |
enum [lastName, firstName, district, school, grade, birthDate] |
[lastName] |
direction |
Direction for sorting. |
- |
enum [asc, desc] |
[asc] |
grade |
The grade of users to limit results to. Values should be from ONIX codelist 77 for US grades, BIC for UK grades. |
- |
String |
null |
sponsorList |
Filter options for limiting results to a specific subset of members. |
- |
enum [allMembers, myQuickList, individualMembers, orgMembers] |
null |
Responses
| HTTP Code | Message | Datatype |
|---|---|---|
200 |
Member Summary List response |
|
0 |
Unexpected error |
Example HTTP request
GET /v2/myOrganization/members?api_key=abcdefg HTTP/1.1
Host: api.bookshare.orgExample HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 1221
{
"limit" : 10,
"next" : null,
"totalResults" : 1,
"memberSummaries" : [ {
"allows" : [ "PUT" ],
"userAccountId" : "AP5xvS9bztz6ybiqkSIXp7VQQZPihRGp1Y1pVYTTaVXg2dpVrzDsNm5Q3uRxGS7Pl929nBh58YBD",
"userName" : "OM_userName",
"name" : {
"firstName" : "Org",
"lastName" : "Member",
"middle" : null,
"prefix" : null,
"suffix" : null,
"links" : [ ]
},
"emailAddress" : null,
"grade" : "6",
"dateOfBirth" : "2015-07-15",
"disabilities" : [ "learning" ],
"plans" : [ "iep" ],
"roles" : [ "organizationMember" ],
"onQuickList" : false,
"preferredFormat" : {
"formatId" : "DAISY",
"name" : "DAISY"
},
"allowAdultContent" : false,
"phoneNumber" : null,
"language" : "eng",
"hasAgreement" : false,
"locked" : false,
"canDownload" : true,
"sponsorManageable" : true,
"links" : [ {
"rel" : "self",
"href" : "https://api.bookshare.org/v2/myOrganization/members/AP5xvS9bztz6ybiqkSIXp7VQQZPihRGp1Y1pVYTTaVXg2dpVrzDsNm5Q3uRxGS7Pl929nBh58YBD"
} ]
} ],
"links" : [ {
"rel" : "self",
"href" : "https://api.bookshare.org/v2/myOrganization/members?api_key=abcdefg"
} ]
}Example Curl request
$ curl 'https://api.bookshare.org/v2/myOrganization/members?api_key=abcdefg' -i -X GET2.5.5. Get a list of sponsors of my organization
GET /v2/myOrganization/sponsors
Description
As a sponsor, get a list of sponsors of my organization.
Parameters
Query Parameters
| Name | Description | Required | Schema | Default |
|---|---|---|---|---|
start |
If null or empty, it means to start at the beginning of the result set. Otherwise, it should be the value of 'next' that was returned from the previous request. |
- |
String |
null |
limit |
Maximum number of results to include. The maximum allowed is 100. |
- |
Integer |
10 |
sortOrder |
Primary sorting field. |
- |
enum [lastName, firstName, district, school, grade, birthDate] |
[lastName] |
direction |
Direction for sorting. |
- |
enum [asc, desc] |
[asc] |
Responses
| HTTP Code | Message | Datatype |
|---|---|---|
200 |
Sponsor Summary List response |
|
0 |
Unexpected error |
Example HTTP request
GET /v2/myOrganization/sponsors?api_key=abcdefg HTTP/1.1
Host: api.bookshare.orgExample HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 818
{
"limit" : 10,
"next" : null,
"totalResults" : 1,
"sponsorSummaries" : [ {
"allows" : [ "PUT" ],
"userAccountId" : "AP5xvS9bztz6ybiqkSIXp7VQQZPihRGp1Y1pVYTTaVXg2dpVrzDsNm5Q3uRxGS7Pl929nBh58YBD",
"name" : {
"firstName" : "Org",
"lastName" : "Sponsor",
"middle" : null,
"prefix" : null,
"suffix" : null,
"links" : [ ]
},
"emailAddress" : "sponsor@school.org",
"phoneNumber" : "123-456-7890",
"title" : "SponsorTitle",
"links" : [ {
"rel" : "self",
"href" : "https://api.bookshare.org/v2/myOrganization/sponsors/AP5xvS9bztz6ybiqkSIXp7VQQZPihRGp1Y1pVYTTaVXg2dpVrzDsNm5Q3uRxGS7Pl929nBh58YBD"
} ]
} ],
"links" : [ {
"rel" : "self",
"href" : "https://api.bookshare.org/v2/myOrganization/sponsors?api_key=abcdefg"
} ]
}Example Curl request
$ curl 'https://api.bookshare.org/v2/myOrganization/sponsors?api_key=abcdefg' -i -X GET2.5.6. Get my organization summary
GET /v2/myOrganization
Description
Request an organization account summary of the authenticated sponsor making the request.
Responses
| HTTP Code | Message | Datatype |
|---|---|---|
200 |
Organization summary response |
|
0 |
Unexpected error |
Example HTTP request
GET /v2/myOrganization?api_key=abcdefg HTTP/1.1
Host: api.bookshare.orgExample HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 1275
{
"allows" : null,
"organizationName" : "Example organization",
"address" : {
"address1" : "123 Main Street",
"address2" : null,
"city" : "SmallTown",
"state" : "CA",
"country" : "US",
"postalCode" : "98765"
},
"phoneNumber" : "123-456-7890",
"webSite" : "exampleorg.com",
"organizationType" : "usPublicK12",
"primaryContact" : {
"allows" : [ "PUT" ],
"userAccountId" : "AP5xvS9bztz6ybiqkSIXp7VQQZPihRGp1Y1pVYTTaVXg2dpVrzDsNm5Q3uRxGS7Pl929nBh58YBD",
"name" : {
"firstName" : "John",
"lastName" : "Doe",
"middle" : null,
"prefix" : null,
"suffix" : null,
"links" : [ ]
},
"emailAddress" : "primarycontact@exampleorg.com",
"phoneNumber" : "789-123-456",
"title" : "Manager",
"links" : [ {
"rel" : "self",
"href" : "https://api.bookshare.org/v2/myOrganization/sponsors/AP5xvS9bztz6ybiqkSIXp7VQQZPihRGp1Y1pVYTTaVXg2dpVrzDsNm5Q3uRxGS7Pl929nBh58YBD"
} ]
},
"links" : [ {
"rel" : "self",
"href" : "https://api.bookshare.org/v2/myOrganization"
}, {
"rel" : "members",
"href" : "https://api.bookshare.org/v2/myOrganization/members"
}, {
"rel" : "sponsors",
"href" : "https://api.bookshare.org/v2/myOrganization/sponsors"
} ]
}Example Curl request
$ curl 'https://api.bookshare.org/v2/myOrganization?api_key=abcdefg' -i -X GET2.5.7. Get a list of title availabilities for the members of my organization.
GET /v2/myOrganization/titleAvailabilities/{bookshareId}
Description
As a sponsor, get a list of the members of my organization, including any alerts that prevent members from accessing the specific title.
Parameters
Path Parameters
| Name | Description | Required | Schema | Default |
|---|---|---|---|---|
bookshareId |
The title identifier of the title to check member access to. |
X |
String |
null |
Query Parameters
| Name | Description | Required | Schema | Default |
|---|---|---|---|---|
start |
If null or empty, it means to start at the beginning of the result set. Otherwise, it should be the value of 'next' that was returned from the previous request. |
- |
String |
null |
limit |
Maximum number of results to include. The maximum allowed is 100. |
- |
Integer |
10 |
sortOrder |
Primary sorting field. |
- |
enum [lastName, firstName, district, school, grade, birthDate] |
[lastName] |
direction |
Direction for sorting. |
- |
enum [asc, desc] |
[asc] |
grade |
The grade of users to limit results to. Values should be from ONIX codelist 77 for US grades, BIC for UK grades. |
- |
String |
null |
districtId |
Unique identifier of the school district to limit results to. |
- |
Integer |
null |
schoolId |
Unique identifier of the school to limit results to. |
- |
Integer |
null |
sponsorList |
Filter options for limiting results to a specific subset of members. |
- |
enum [allMembers, myQuickList, individualMembers, orgMembers] |
null |
Responses
| HTTP Code | Message | Datatype |
|---|---|---|
200 |
Member Title Availability response |
|
0 |
Unexpected error |
Example HTTP request
GET /v2/myOrganization/titleAvailabilities/12345?api_key=abcdefg HTTP/1.1
Host: api.bookshare.orgExample HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 932
{
"limit" : 10,
"next" : null,
"totalResults" : 1,
"memberTitleAvailabilities" : [ {
"allows" : null,
"userAccountId" : "AP5xvS9bztz6ybiqkSIXp7VQQZPihRGp1Y1pVYTTaVXg2dpVrzDsNm5Q3uRxGS7Pl929nBh58YBD",
"userName" : "OM_userName",
"name" : {
"firstName" : "Org",
"lastName" : "Member",
"middle" : null,
"prefix" : null,
"suffix" : null,
"links" : [ ]
},
"emailAddress" : null,
"grade" : "6",
"dateOfBirth" : "2015-07-15",
"disabilities" : [ "learning" ],
"plans" : [ "iep" ],
"roles" : [ "organizationMember" ],
"onQuickList" : false,
"preferredFormat" : {
"formatId" : "DAISY",
"name" : "DAISY"
},
"titleAccessAlerts" : null,
"assigned" : true,
"links" : [ ]
} ],
"links" : [ {
"rel" : "self",
"href" : "https://api.bookshare.org/v2/myOrganization/titleAvailabilities/12345?api_key=abcdefg"
} ]
}Example Curl request
$ curl 'https://api.bookshare.org/v2/myOrganization/titleAvailabilities/12345?api_key=abcdefg' -i -X GET2.5.8. Get organization types
GET /v2/organizationTypes
Description
Get the list of organization types relevant to the current user.
Responses
| HTTP Code | Message | Datatype |
|---|---|---|
200 |
Organization type list response. |
|
0 |
Unexpected error |
Example HTTP request
GET /v2/organizationTypes?api_key=abcdefg HTTP/1.1
Host: api.bookshare.orgExample HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 592
{
"organizationTypes" : [ {
"name" : "usPublicK12",
"description" : "US K-12 Public School"
}, {
"name" : "usPrivateUniversity",
"description" : "US Private Accredited Colleges and Universities"
}, {
"name" : "libraryPublic",
"description" : "Public Library"
}, {
"name" : "ukPrimarySchool",
"description" : "UK Primary / Middle School"
}, {
"name" : "internationalK12SchoolAgency",
"description" : "Non-US K-12 School or Agency"
} ],
"links" : [ {
"rel" : "self",
"href" : "https://api.bookshare.org/v2/organizationTypes"
} ]
}Example Curl request
$ curl 'https://api.bookshare.org/v2/organizationTypes?api_key=abcdefg' -i -X GET2.5.9. Look up reference organizations
GET /v2/referenceOrganizations
Description
Search for reference organizations to help users create their organization in the Bookshare system. Only available to anonymous users on certain API clients.
Parameters
Query Parameters
| Name | Description | Required | Schema | Default |
|---|---|---|---|---|
state |
The reference organization’s state or province. The value should be either a two-character postal abbreviation or an ISO 3166-2 subdivision code for the user’s country. |
X |
String |
null |
name |
The reference organization’s name. |
- |
String |
null |
city |
The reference organization’s city. |
- |
String |
null |
organizationTypes |
Limit results to the given types of organizations. List of possible values exists at /v2/organizationTypes. Enter each organization type as a separate instance of this parameter. |
- |
String, multi |
null |
start |
If null or empty, it means to start at the beginning of the result set. Otherwise, it should be the value of 'next' that was returned from the previous request. |
- |
String |
null |
limit |
Maximum number of results to include. The maximum allowed is 100. |
- |
Integer |
10 |
direction |
Direction for sorting by name. |
- |
enum [asc, desc] |
[asc] |
Responses
| HTTP Code | Message | Datatype |
|---|---|---|
200 |
Reference Organization response |
|
0 |
Unexpected error |
Example HTTP request
GET /v2/referenceOrganizations?state=CA&name=example&organizationTypes=usPublicK12&organizationTypes=usPrivateK12&api_key=abcdefg HTTP/1.1
Host: api.bookshare.orgExample HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 614
{
"limit" : 10,
"next" : null,
"totalResults" : 1,
"referenceOrganizations" : [ {
"referenceOrgId" : "123",
"name" : "Example School",
"parentName" : "Example District",
"address" : {
"address1" : "123 Main Street",
"address2" : null,
"city" : "SmallTown",
"state" : "CA",
"country" : "US",
"postalCode" : "98765"
},
"locationAddress" : null,
"links" : [ ]
} ],
"links" : [ {
"rel" : "self",
"href" : "https://api.bookshare.org/v2/referenceOrganizations?state=CA&name=example&organizationTypes=usPublicK12&api_key=abcdefg"
} ]
}Example Curl request
$ curl 'https://api.bookshare.org/v2/referenceOrganizations?state=CA&name=example&organizationTypes=usPublicK12&organizationTypes=usPrivateK12&api_key=abcdefg' -i -X GET2.5.10. Update my organization's information
PUT /v2/myOrganization
Description
As my organization’s primary contact, update my organization’s information. This includes name, address, and other properties.
Parameters
Form Parameters
| Name | Description | Required | Schema | Default |
|---|---|---|---|---|
organizationName |
The name of the organization. |
- |
String |
null |
address1 |
The organization’s street address. |
- |
String |
null |
address2 |
Any extra street address information for the organization. |
- |
String |
null |
city |
The organization’s city. |
- |
String |
null |
state |
The organization’s state or province. The value should be either a two-character postal abbreviation or an ISO 3166-2 subdivision code for the user’s country. This field is only relevant for subdivisions of the US and Canada. |
- |
String |
null |
country |
The organization’s country. The values should be a two-character ISO 3166 alpha-2 country code. |
- |
String |
null |
postalCode |
The organization’s postal code. |
- |
String |
null |
phoneNumber |
The organization’s phone number. |
- |
String |
null |
website |
The organization’s website. |
- |
String |
null |
Responses
| HTTP Code | Message | Datatype |
|---|---|---|
200 |
Organization summary response |
|
0 |
Unexpected error |
Example HTTP request
PUT /v2/myOrganization HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: api.bookshare.org
Content-Length: 98
organizationName=New+Organization+Name&address1=456+Main+Street&address2=Suite+789&api_key=abcdefgExample HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 1288
{
"allows" : [ "PUT" ],
"organizationName" : "New Organization Name",
"address" : {
"address1" : "456 Main Street",
"address2" : "Suite 789",
"city" : "SmallTown",
"state" : "CA",
"country" : "US",
"postalCode" : "98765"
},
"phoneNumber" : "123-456-7890",
"webSite" : "exampleorg.com",
"organizationType" : "usPublicK12",
"primaryContact" : {
"allows" : [ "PUT" ],
"userAccountId" : "AP5xvS9bztz6ybiqkSIXp7VQQZPihRGp1Y1pVYTTaVXg2dpVrzDsNm5Q3uRxGS7Pl929nBh58YBD",
"name" : {
"firstName" : "John",
"lastName" : "Doe",
"middle" : null,
"prefix" : null,
"suffix" : null,
"links" : [ ]
},
"emailAddress" : "primarycontact@exampleorg.com",
"phoneNumber" : "789-123-456",
"title" : "Manager",
"links" : [ {
"rel" : "self",
"href" : "https://api.bookshare.org/v2/myOrganization/sponsors/AP5xvS9bztz6ybiqkSIXp7VQQZPihRGp1Y1pVYTTaVXg2dpVrzDsNm5Q3uRxGS7Pl929nBh58YBD"
} ]
},
"links" : [ {
"rel" : "self",
"href" : "https://api.bookshare.org/v2/myOrganization"
}, {
"rel" : "members",
"href" : "https://api.bookshare.org/v2/myOrganization/members"
}, {
"rel" : "sponsors",
"href" : "https://api.bookshare.org/v2/myOrganization/sponsors"
} ]
}Example Curl request
$ curl 'https://api.bookshare.org/v2/myOrganization' -i -X PUT \
-d 'organizationName=New+Organization+Name&address1=456+Main+Street&address2=Suite+789&api_key=abcdefg'2.5.11. Update a member's information
PUT /v2/myOrganization/members/{userIdentifier}
Description
As a sponsor, edit the basic information of a member in my organization.
Parameters
Path Parameters
| Name | Description | Required | Schema | Default |
|---|---|---|---|---|
userIdentifier |
The unique identifying username or userAccountId of the member to update. |
X |
String |
null |
Form Parameters
| Name | Description | Required | Schema | Default |
|---|---|---|---|---|
firstName |
The user’s first name. Only editable for members where sponsorManageable is true. |
- |
String |
null |
lastName |
The user’s last name. Only editable for members where sponsorManageable is true. |
- |
String |
null |
dateOfBirth |
The user’s date of birth. The value should be formatted as 'YYYY-MM-DD'. |
- |
String |
null |
grade |
User’s current grade. Values are from ONIX codelist 77 for US grades, BIC for UK grades |
- |
String |
null |
username |
Username for the user. Only editable for members where sponsorManageable is true. |
- |
String |
null |
password |
The user’s password. It must be from 8-32 characters long, and contain at least one letter and one number. Only editable for members where sponsorManageable is true. |
- |
String |
null |
onQuickList |
True if the user should be added to the quicklist of the sponsor making the request, false to remove from the quicklist. |
- |
Boolean |
null |
disabilityType |
The types of disabilities involved. Enter each disability type as a separate instance of this parameter. Only editable for members where sponsorManageable is true. |
- |
enum [visual, learning, physical, nonspecific] |
null |
disabilityPlan |
The disability plan for the user. Enter each disability plan as a separate instance of this parameter. Only editable for members where sponsorManageable is true. |
- |
enum [iep, section504] |
null |
Responses
| HTTP Code | Message | Datatype |
|---|---|---|
200 |
Member Summary response |
|
0 |
Unexpected error |
Example HTTP request
PUT /v2/myOrganization/members/2000 HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: api.bookshare.org
Content-Length: 58
firstName=Newname&grade=8&onQuickList=true&api_key=abcdefgExample HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 945
{
"allows" : [ "PUT" ],
"userAccountId" : "AP5xvS9bztz6ybiqkSIXp7VQQZPihRGp1Y1pVYTTaVXg2dpVrzDsNm5Q3uRxGS7Pl929nBh58YBD",
"userName" : "OM_userName",
"name" : {
"firstName" : "Newname",
"lastName" : "Member",
"middle" : null,
"prefix" : null,
"suffix" : null,
"links" : [ ]
},
"emailAddress" : null,
"grade" : "8",
"dateOfBirth" : "2015-07-15",
"disabilities" : [ "learning" ],
"plans" : [ "iep" ],
"roles" : [ "organizationMember" ],
"onQuickList" : true,
"preferredFormat" : {
"formatId" : "DAISY",
"name" : "DAISY"
},
"allowAdultContent" : false,
"phoneNumber" : null,
"language" : "eng",
"hasAgreement" : false,
"locked" : false,
"canDownload" : true,
"sponsorManageable" : true,
"links" : [ {
"rel" : "self",
"href" : "https://api.bookshare.org/v2/myOrganization/members/AP5xvS9bztz6ybiqkSIXp7VQQZPihRGp1Y1pVYTTaVXg2dpVrzDsNm5Q3uRxGS7Pl929nBh58YBD"
} ]
}Example Curl request
$ curl 'https://api.bookshare.org/v2/myOrganization/members/2000' -i -X PUT \
-d 'firstName=Newname&grade=8&onQuickList=true&api_key=abcdefg'2.5.12. Update my organization's primary contact
PUT /v2/myOrganization/primaryContact
Description
As my organization’s primary contact, change my organization’s primary contact to a different sponsor.
Parameters
Form Parameters
| Name | Description | Required | Schema | Default |
|---|---|---|---|---|
userIdentifier |
The unique identifying username or userAccountId of the new primary contact. |
X |
String |
null |
Responses
| HTTP Code | Message | Datatype |
|---|---|---|
200 |
Sponsor Summary response |
|
0 |
Unexpected error |
Example HTTP request
PUT /v2/myOrganization/primaryContact HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: api.bookshare.org
Content-Length: 51
userIdentifier=sponsor%40school.org&api_key=abcdefgExample HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 569
{
"allows" : [ "PUT" ],
"userAccountId" : "AP5xvS9bztz6ybiqkSIXp7VQQZPihRGp1Y1pVYTTaVXg2dpVrzDsNm5Q3uRxGS7Pl929nBh58YBD",
"name" : {
"firstName" : "Org",
"lastName" : "Sponsor",
"middle" : null,
"prefix" : null,
"suffix" : null,
"links" : [ ]
},
"emailAddress" : "sponsor@school.org",
"phoneNumber" : "123-456-7890",
"title" : "SponsorTitle",
"links" : [ {
"rel" : "self",
"href" : "https://api.bookshare.org/v2/myOrganization/sponsors/AP5xvS9bztz6ybiqkSIXp7VQQZPihRGp1Y1pVYTTaVXg2dpVrzDsNm5Q3uRxGS7Pl929nBh58YBD"
} ]
}Example Curl request
$ curl 'https://api.bookshare.org/v2/myOrganization/primaryContact' -i -X PUT \
-d 'userIdentifier=sponsor%40school.org&api_key=abcdefg'2.5.13. Update a sponsor's information
PUT /v2/myOrganization/sponsors/{userIdentifier}
Description
As a sponsor, edit the basic information of another sponsor in my organization.
Parameters
Path Parameters
| Name | Description | Required | Schema | Default |
|---|---|---|---|---|
userIdentifier |
The unique identifying username or userAccountId of the sponsor to update. |
X |
String |
null |
Form Parameters
| Name | Description | Required | Schema | Default |
|---|---|---|---|---|
firstName |
The sponsor’s first name. |
- |
String |
null |
lastName |
The sponsor’s last name. |
- |
String |
null |
phoneNumber |
The sponsor’s phone number. |
- |
String |
null |
emailAddress |
The sponsor’s email address. This value will also be used as the username. |
- |
String |
null |
title |
The sponsor’s job title. |
- |
String |
null |
Responses
| HTTP Code | Message | Datatype |
|---|---|---|
200 |
Sponsor Summary response |
|
0 |
Unexpected error |
Example HTTP request
PUT /v2/myOrganization/sponsors/sponsor@school.org HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: api.bookshare.org
Content-Length: 38
title=New+SponsorTitle&api_key=abcdefgExample HTTP response
HTTP/1.1 200 OK
Content-Disposition: inline;filename=f.txt
Content-Type: application/json
Content-Length: 573
{
"allows" : [ "PUT" ],
"userAccountId" : "AP5xvS9bztz6ybiqkSIXp7VQQZPihRGp1Y1pVYTTaVXg2dpVrzDsNm5Q3uRxGS7Pl929nBh58YBD",
"name" : {
"firstName" : "Org",
"lastName" : "Sponsor",
"middle" : null,
"prefix" : null,
"suffix" : null,
"links" : [ ]
},
"emailAddress" : "sponsor@school.org",
"phoneNumber" : "123-456-7890",
"title" : "New SponsorTitle",
"links" : [ {
"rel" : "self",
"href" : "https://api.bookshare.org/v2/myOrganization/sponsors/AP5xvS9bztz6ybiqkSIXp7VQQZPihRGp1Y1pVYTTaVXg2dpVrzDsNm5Q3uRxGS7Pl929nBh58YBD"
} ]
}Example Curl request
$ curl 'https://api.bookshare.org/v2/myOrganization/sponsors/sponsor@school.org' -i -X PUT \
-d 'title=New+SponsorTitle&api_key=abcdefg'2.6. Periodicals
A periodical represents a magazine or newspaper, each of which can have multiple editions/issues. The editions/issues are available to users in the same way as titles, based on characteristics of the user and the periodical, and in formats that will be specified in the response.
2.6.1. Download a periodical file resource
GET /v2/periodicals/{seriesId}/editions/{editionId}/{format}/resources/{resourceId}
Description
Download a single title file resource that is part of a periodical artifact. Note: this URL will be constructed by the system, and appear in the periodical file resources response.
Parameters
Path Parameters
| Name | Description | Required | Schema | Default |
|---|---|---|---|---|
seriesId |
The unique identifier of a periodical series |
X |
String |
null |
editionId |
The unique identifier of a periodical edition |
X |
String |
null |
format |
The format of the title artifact |
X |
enum [DAISY, DAISY_AUDIO, DAISY_2_AUDIO, BRF, EPUB3, PDF, DOCX] |
null |
resourceId |
Unique identifier of the periodical file resource |
X |
String |
null |
Query Parameters
| Name | Description | Required | Schema | Default |
|---|---|---|---|---|
speed |
Playback speed rate, for mp3 file only. Numerical value from 0.5 to 3.5, as a multiplier, in increments of 0.05. If not included then the default speed is 1. |
- |
Float |
null |
Responses
| HTTP Code | Message | Datatype |
|---|---|---|
302 |
Redirect to the header location |
|
0 |
Unexpected error |
Example HTTP request
GET /v2/periodicals/1343455/editions/34444/DAISY/resources/333?api_key=abcdefg HTTP/1.1
Host: api.bookshare.orgExample HTTP response
HTTP/1.1 302 Found
Location: http://exampleurl.com
Content-Type: application/json
Content-Length: 69
{
"key" : "AVAILABLE",
"messages" : [ "http://exampleurl.com" ]
}Example Curl request
$ curl 'https://api.bookshare.org/v2/periodicals/1343455/editions/34444/DAISY/resources/333?api_key=abcdefg' -i -X GET2.6.2. Get a list of title file resources for a periodical
GET /v2/periodicals/{seriesId}/editions/{editionId}/{format}/resources
Description
Ask for a list of file resources for a periodical artifact of the given format. This will give a list of information about each file that makes up the artifact, including a link to retrieve each file. MP3-compatible reading systems can use the DAISY_AUDIO format to get references to .mp3 files.
Parameters
Path Parameters
| Name | Description | Required | Schema | Default |
|---|---|---|---|---|
seriesId |
The unique identifier of a periodical series |
X |
String |
null |
editionId |
The unique identifier of a periodical edition |
X |
String |
null |
format |
The format of the title artifact |
X |
enum [DAISY, DAISY_AUDIO, DAISY_2_AUDIO, BRF, EPUB3, PDF, DOCX] |
null |
Query Parameters
| Name | Description | Required | Schema | Default |
|---|---|---|---|---|
limit |
Maximum number of file resources to list. Maximum allowed is 100. |
- |
Integer |
10 |
start |
If null or empty, it means to start at the beginning of the result set. Otherwise, it should be the value of 'next' that was returned from the previous request. |
- |
String |
null |
Responses
| HTTP Code | Message | Datatype |
|---|---|---|
200 |
Title file resource collection response |
|
0 |
Unexpected error |
Example HTTP request
GET /v2/periodicals/1343455/editions/122/BRF/resources?api_key=abcdefg HTTP/1.1
Host: api.bookshare.orgExample HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 457
{
"limit" : 10,
"next" : null,
"totalResults" : 1,
"titleFileResources" : [ {
"mimeType" : "image/jpeg",
"size" : 10000000,
"localURI" : "./images/sun001.jpg",
"lastModifiedDate" : "2019-06-01T00:00:00Z",
"links" : [ {
"rel" : "self",
"href" : "http://exampleurl.com"
} ]
} ],
"links" : [ {
"rel" : "self",
"href" : "https://api.bookshare.org/v2/periodicals/1343455/editions/122/BRF/resources"
} ]
}Example Curl request
$ curl 'https://api.bookshare.org/v2/periodicals/1343455/editions/122/BRF/resources?api_key=abcdefg' -i -X GET2.6.3. Download a periodical edition
GET /v2/periodicals/{seriesId}/editions/{editionId}/{format}
Description
Ask for a periodical edition file of a given format. This will request a package of a periodical edition artifact, which will be fingerprinted and watermarked to indicate it’s delivery to either the current user, or the 'forUser' if that is specified. If the package is not available immediately, requests to this endpoint will simply return a status to acknowledge receipt. Subsequent requests will eventually return a reference to the delivery file for the given format (ZIP, EPUB, PDF, etc).
Parameters
Path Parameters
| Name | Description | Required | Schema | Default |
|---|---|---|---|---|
seriesId |
Unique identifier of a periodical |
X |
String |
null |
editionId |
Unique identifier of a periodical edition |
X |
String |
null |
format |
The format of the periodical edition artifact |
X |
enum [DAISY, DAISY_AUDIO, DAISY_2_AUDIO, BRF, EPUB3, PDF, DOCX] |
null |
Query Parameters
| Name | Description | Required | Schema | Default |
|---|---|---|---|---|
forUser |
If the download is on behalf of a member, the member identifier |
- |
String |
null |
Responses
| HTTP Code | Message | Datatype |
|---|---|---|
202 |
Request has been received, and will be processed. |
|
302 |
Redirect to the header location |
|
0 |
Unexpected error |
Example HTTP request
GET /v2/periodicals/100/editions/1001/DAISY?api_key=abcdefg HTTP/1.1
Host: api.bookshare.orgExample HTTP response
HTTP/1.1 202 Accepted
Cache-Control: max-age=60
Content-Type: application/json
Content-Length: 76
{
"key" : "SUBMITTED",
"messages" : [ "Packaging requested for 1001" ]
}Example Curl request
$ curl 'https://api.bookshare.org/v2/periodicals/100/editions/1001/DAISY?api_key=abcdefg' -i -X GET2.6.4. Get periodical editions
GET /v2/periodicals/{seriesId}/editions
Description
Get a list editions for a periodical. The result will be a collection of periodical edition resources, with a paging token if the results are more than the paging limit.
Parameters
Path Parameters
| Name | Description | Required | Schema | Default |
|---|---|---|---|---|
seriesId |
Unique identifier of a periodical series. |
X |
String |
null |
Query Parameters
| Name | Description | Required | Schema | Default |
|---|---|---|---|---|
limit |
Maximum number of results to include. The maximum allowed is 100. |
- |
Integer |
10 |
sortOrder |
Primary sorting field. |
- |
enum [title, publicationDate] |
[title] |
direction |
Direction for sorting. |
- |
enum [asc, desc] |
[asc] |
start |
If null or empty, it means to start at the beginning of the result set. Otherwise, it should be the value of 'next' that was returned from the previous request. |
- |
String |
null |
Responses
| HTTP Code | Message | Datatype |
|---|---|---|
200 |
Periodical edition list metadata response |
|
0 |
Unexpected error |
Example HTTP request
GET /v2/periodicals/100/editions?api_key=abcdefg HTTP/1.1
Host: api.bookshare.orgExample HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 820
{
"limit" : 10,
"next" : null,
"totalResults" : 1,
"periodicalEditions" : [ {
"editionId" : 1001,
"editionName" : "Los Angeles Times",
"expirationDate" : "2020-01-01T00:00:00Z",
"publicationDate" : "2018-01-01T00:00:00Z",
"formats" : [ {
"formatId" : "DAISY",
"name" : "DAISY"
}, {
"formatId" : "BRF",
"name" : "BRF"
}, {
"formatId" : "DAISY_AUDIO",
"name" : "Audio"
}, {
"formatId" : "EPUB3",
"name" : "EPUB 3"
} ],
"links" : [ {
"rel" : "download",
"href" : "https://api.bookshare.org/v2/periodicals/100/editions/1001/{format}"
} ]
} ],
"allows" : null,
"message" : null,
"links" : [ {
"rel" : "self",
"href" : "https://api.bookshare.org/v2/periodicals/100/editions?api_key=abcdefg"
} ]
}Example Curl request
$ curl 'https://api.bookshare.org/v2/periodicals/100/editions?api_key=abcdefg' -i -X GET2.6.5. Search for periodicals
GET /v2/periodicals
Description
To discover periodicals in the collection, you can ask for the collection of periodical series resources, filtered by a title string or ISSN. The result will be a collection of periodical series metadata resources, with a paging token if the results are more than the paging limit.
Parameters
Query Parameters
| Name | Description | Required | Schema | Default |
|---|---|---|---|---|
title |
Search string to use to match the title of a periodical. |
- |
String |
null |
issn |
Search string to use to match the ISSN of a periodical. |
- |
String |
null |
language |
Language code to use to match the language of the periodical. The value should be a three-character ISO 639-2 alpha-3 language code. |
- |
String |
null |
start |
If null or empty, it means to start at the beginning of the result set. Otherwise, it should be the value of 'next' that was returned from the previous request. |
- |
String |
null |
limit |
Maximum number of results to include. The maximum allowed is 100. |
- |
Integer |
10 |
sortOrder |
Primary sorting field. |
- |
enum [title, issn] |
[title] |
direction |
Direction for sorting. |
- |
enum [asc, desc] |
[asc] |
Responses
| HTTP Code | Message | Datatype |
|---|---|---|
200 |
Periodical series metadata collection response |
|
0 |
Unexpected error |
Example HTTP request
GET /v2/periodicals?title=USA&limit=25&sortOrder=title&api_key=abcdefg HTTP/1.1
Host: api.bookshare.orgExample HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 1285
{
"limit" : 25,
"next" : null,
"totalResults" : 1,
"periodicals" : [ {
"seriesId" : 123,
"title" : "USA Today",
"issn" : "0734-7456",
"description" : "Latest World and US News",
"publisher" : "Gannett Company, Inc.",
"seriesType" : "",
"externalCategoryCode" : "extCode1",
"categories" : [ {
"name" : "Politics and Government",
"description" : "Politics and Government",
"categoryType" : "Bookshare",
"code" : null,
"links" : [ ]
}, {
"name" : "POLITICAL SCIENCE / General",
"description" : "POLITICAL SCIENCE / General",
"categoryType" : "BISAC",
"code" : "POL000000",
"links" : [ ]
} ],
"languages" : [ "eng" ],
"countries" : [ "US" ],
"editionCount" : 10,
"latestEdition" : {
"editionId" : 456,
"editionName" : "April 1, 2018"
},
"links" : [ {
"rel" : "self",
"href" : "https://api.bookshare.org/v2/periodicals/123"
}, {
"rel" : "editions",
"href" : "https://api.bookshare.org/v2/periodicals/123/editions"
} ]
} ],
"allows" : null,
"message" : null,
"links" : [ {
"rel" : "self",
"href" : "https://api.bookshare.org/v2/periodicals?title=USA&limit=25&sortOrder=title&api_key=abcdefg"
} ]
}Example Curl request
$ curl 'https://api.bookshare.org/v2/periodicals?title=USA&limit=25&sortOrder=title&api_key=abcdefg' -i -X GET2.6.6. Get periodical series metadata
GET /v2/periodicals/{seriesId}
Description
Ask for a periodical series’s metadata. This includes ISSN, latest edition and other properties.
Parameters
Path Parameters
| Name | Description | Required | Schema | Default |
|---|---|---|---|---|
seriesId |
Unique identifier of a periodical series |
X |
String |
null |
Responses
| HTTP Code | Message | Datatype |
|---|---|---|
200 |
Periodical series metadata detail response |
|
0 |
Unexpected error |
Example HTTP request
GET /v2/periodicals/123?api_key=abcdefg HTTP/1.1
Host: api.bookshare.orgExample HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 945
{
"seriesId" : 123,
"title" : "USA Today",
"issn" : "0734-7456",
"description" : "Latest World and US News",
"publisher" : "Gannett Company, Inc.",
"seriesType" : "",
"externalCategoryCode" : "extCode1",
"categories" : [ {
"name" : "Politics and Government",
"description" : "Politics and Government",
"categoryType" : "Bookshare",
"code" : null,
"links" : [ ]
}, {
"name" : "POLITICAL SCIENCE / General",
"description" : "POLITICAL SCIENCE / General",
"categoryType" : "BISAC",
"code" : "POL000000",
"links" : [ ]
} ],
"languages" : [ "eng" ],
"countries" : [ "US" ],
"editionCount" : 10,
"latestEdition" : {
"editionId" : 456,
"editionName" : "April 1, 2018"
},
"links" : [ {
"rel" : "self",
"href" : "https://api.bookshare.org/v2/periodicals/123"
}, {
"rel" : "editions",
"href" : "https://api.bookshare.org/v2/periodicals/123/editions"
} ]
}Example Curl request
$ curl 'https://api.bookshare.org/v2/periodicals/123?api_key=abcdefg' -i -X GET2.7. Popular Lists
Popular Lists represents several collections of titles that are most popular on Bookshare. These include the most popular titles over the last year, over the last month, and by category.
2.7.1. Get a list of popular titles
GET /v2/popularLists/{popularListId}
Description
Get a list of popular titles in a given category or time period.
Parameters
Path Parameters
| Name | Description | Required | Schema | Default |
|---|---|---|---|---|
popularListId |
The id of the popular list to get. |
X |
String |
null |
Query Parameters
| Name | Description | Required | Schema | Default |
|---|---|---|---|---|
start |
If null or empty, it means to start at the beginning of the result set. Otherwise, it should be the value of 'next' that was returned from the previous request. |
- |
String |
null |
limit |
Maximum number of results to include. The maximum allowed is 100. |
- |
Integer |
10 |
Responses
| HTTP Code | Message | Datatype |
|---|---|---|
200 |
Popular List response |
|
0 |
Unexpected error |
Example HTTP request
GET /v2/popularLists/bW9zdFBvcHVsYXI6Qk9PS1NIQVJFOjcyMA==?api_key=abcdefg HTTP/1.1
Host: api.bookshare.orgExample HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 2670
{
"limit" : 10,
"next" : null,
"totalResults" : 1,
"popularTitles" : [ {
"allows" : null,
"bookshareId" : 101175,
"title" : "Little House on the Prairie",
"subtitle" : null,
"authors" : [ {
"firstName" : "Laura",
"lastName" : "Wilder",
"middle" : "Ingalls",
"prefix" : null,
"suffix" : null,
"links" : [ ]
} ],
"isbn13" : "9780060264451",
"synopsis" : "The adventures continue for Laura Ingalls and her family as they leave their little house in the Big Woods of Wisconsin and set out for Kansas.",
"seriesTitle" : "Little House",
"seriesNumber" : "3",
"copyrightDate" : "1970",
"publishDate" : "2009-07-24T00:00:00Z",
"formats" : [ {
"formatId" : "DAISY",
"name" : "DAISY"
}, {
"formatId" : "BRF",
"name" : "BRF"
}, {
"formatId" : "DAISY_AUDIO",
"name" : "Audio"
}, {
"formatId" : "EPUB3",
"name" : "EPUB 3"
} ],
"externalFormats" : [ ],
"titleContentType" : "text",
"available" : true,
"contributors" : [ {
"name" : {
"displayName" : "Laura Ingalls Wilder",
"indexName" : "Wilder, Laura Ingalls",
"links" : [ ]
},
"type" : "author"
} ],
"composers" : null,
"lyricists" : null,
"arrangers" : null,
"translators" : null,
"editors" : null,
"instruments" : null,
"vocalParts" : null,
"languages" : [ "eng" ],
"contentWarnings" : [ ],
"categories" : [ {
"name" : "Literature and Fiction",
"description" : "Literature and Fiction",
"categoryType" : "Bookshare",
"code" : null,
"links" : [ ]
}, {
"name" : "JUVENILE FICTION / General",
"description" : "JUVENILE FICTION / General",
"categoryType" : "BISAC",
"code" : "JUV016011",
"links" : [ ]
} ],
"readingAgeMinimum" : 8,
"readingAgeMaximum" : 12,
"lexileCode" : "HL",
"lexileNumber" : "760L",
"nimac" : false,
"numImages" : 5,
"site" : "bookshare",
"titleAccessAlerts" : null,
"owner" : null,
"links" : [ {
"rel" : "self",
"href" : "https://api.bookshare.org/v2/titles/101175"
}, {
"rel" : "download",
"href" : "https://api.bookshare.org/v2/titles/101175/{format}"
}, {
"rel" : "coverimage",
"href" : "http://covers.bookshare.org/4538345.jpg"
}, {
"rel" : "thumbnail",
"href" : "http://covers.bookshare.org/4538345.jpg"
} ]
} ],
"links" : [ {
"rel" : "self",
"href" : "https://api.bookshare.org/v2/popularLists/bW9zdFBvcHVsYXI6Qk9PS1NIQVJFOjcyMA%3D%3D?api_key=abcdefg"
} ]
}Example Curl request
$ curl 'https://api.bookshare.org/v2/popularLists/bW9zdFBvcHVsYXI6Qk9PS1NIQVJFOjcyMA==?api_key=abcdefg' -i -X GET2.7.2. Get the popular lists
GET /v2/popularLists
Description
Get the list of all available popular lists.
Parameters
Query Parameters
| Name | Description | Required | Schema | Default |
|---|---|---|---|---|
start |
If null or empty, it means to start at the beginning of the result set. Otherwise, it should be the value of 'next' that was returned from the previous request. |
- |
String |
null |
limit |
Maximum number of results to include. The maximum allowed is 100. |
- |
Integer |
10 |
Responses
| HTTP Code | Message | Datatype |
|---|---|---|
200 |
Popular Lists collection response |
|
0 |
Unexpected error |
Example HTTP request
GET /v2/popularLists?api_key=abcdefg HTTP/1.1
Host: api.bookshare.orgExample HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 965
{
"limit" : 10,
"next" : null,
"totalResults" : 4,
"popularLists" : [ {
"id" : "abcdef",
"description" : "Most Popular in the Last Month",
"links" : [ {
"rel" : "self",
"href" : "https://api.bookshare.org/v2/popularLists/abcdef"
} ]
}, {
"id" : "ghijkl",
"description" : "Most Popular in the Last Year",
"links" : [ {
"rel" : "self",
"href" : "https://api.bookshare.org/v2/popularLists/ghijkl"
} ]
}, {
"id" : "mnopqr",
"description" : "Most Popular in Animals",
"links" : [ {
"rel" : "self",
"href" : "https://api.bookshare.org/v2/popularLists/mnopqr"
} ]
}, {
"id" : "stuvwx",
"description" : "Most Popular in History",
"links" : [ {
"rel" : "self",
"href" : "https://api.bookshare.org/v2/popularLists/stuvwx"
} ]
} ],
"links" : [ {
"rel" : "self",
"href" : "https://api.bookshare.org/v2/popularLists?api_key=abcdefg"
} ]
}Example Curl request
$ curl 'https://api.bookshare.org/v2/popularLists?api_key=abcdefg' -i -X GET2.8. Reading Activity
Reading activity refers to a set of events that mark a user's progress through a title. These events are location-based, referring to a span of text that could be a page, chapter, or an arbitrary set of continuous text.
2.8.1. Get my reading position
GET /v2/myReadingPosition/{bookshareId}/{format}
Description
Get my reading position for a specific title format.
Parameters
Path Parameters
| Name | Description | Required | Schema | Default |
|---|---|---|---|---|
bookshareId |
The title identifier of the content being read. |
X |
String |
null |
format |
The artifact being read. |
X |
enum [DAISY, DAISY_AUDIO, DAISY_2_AUDIO, BRF, EPUB3, PDF, DOCX] |
null |
Responses
| HTTP Code | Message | Datatype |
|---|---|---|
200 |
Reading position response |
|
0 |
Unexpected error |
Example HTTP request
GET /v2/myReadingPosition/1041744/EPUB3?api_key=abcdefg HTTP/1.1
Host: api.bookshare.orgExample HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 277
{
"bookshareId" : 1041744,
"format" : {
"formatId" : "EPUB3",
"name" : "EPUB 3"
},
"location" : "book.epub#epubcfi(/6/4[chap01ref]!/4[body01]/10[para05]/3:10)",
"dateAdded" : "2019-01-01T00:00:00Z",
"dateModified" : "2021-12-31T00:00:00Z",
"links" : [ ]
}Example Curl request
$ curl 'https://api.bookshare.org/v2/myReadingPosition/1041744/EPUB3?api_key=abcdefg' -i -X GET2.8.2. Submit a reading activity event
POST /v2/readingEvents
Description
Submit reading activity events that mark different types of reading activity.
Parameters
Form Parameters
| Name | Description | Required | Schema | Default |
|---|---|---|---|---|
bookshareId |
The title identifier of the content being read. |
X |
String |
null |
format |
The artifact being read. |
X |
enum [DAISY, DAISY_AUDIO, DAISY_2_AUDIO, BRF, EPUB3, PDF, DOCX] |
null |
location |
A CFI, 'content fragment identifer', based on the EPUB3 standard. Refer to EPUB Canonical Fragment Identifiers for examples. |
X |
String |
null |
locationDescription |
Description of location that reader could recognize, like chapter heading or page number, as it appears in the content. |
- |
String |
null |
metric |
The metric indicator, describes the quantity of content that was just read. |
X |
Integer |
null |
metricType |
The metric type, such as page or chapter. |
X |
enum [page, chapter, paragraph] |
null |
Example HTTP request
POST /v2/readingEvents HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: api.bookshare.org
Content-Length: 209
bookshareId=2410856&format=DAISY&location=book.epub%23epubcfi%28%2F6%2F4%5Bchap01ref%5D%21%2F4%5Bbody01%5D%2F10%5Bpara05%5D%2F3%3A10%29&locationDescription=Chapter+3&metric=3&metricType=chapter&api_key=abcdefgExample HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 78
{
"key" : "SUCCESS",
"messages" : [ "Reading activity event submitted" ]
}Example Curl request
$ curl 'https://api.bookshare.org/v2/readingEvents' -i -X POST \
-d 'bookshareId=2410856&format=DAISY&location=book.epub%23epubcfi%28%2F6%2F4%5Bchap01ref%5D%21%2F4%5Bbody01%5D%2F10%5Bpara05%5D%2F3%3A10%29&locationDescription=Chapter+3&metric=3&metricType=chapter&api_key=abcdefg'2.9. Reading Lists
Reading lists are a way for members to organize titles. Reading lists can be created and deleted by individual members and sponsors, and titles can be added and removed from them. For sponsors, these lists can also be shared with student members to serve as a type of class syllabus. To do so, a sponsor can add a member from their organization to the reading list, and that member will be able to use that list but will not be able to modify it.
2.9.1. Remove a title from a reading list
DELETE /v2/lists/{readingListId}/titles/{bookshareId}
Description
Remove a title from the specified reading list. The reading list must be one that the user created, or that they have rights to as an organization sponsor or membership assistant.
Parameters
Path Parameters
| Name | Description | Required | Schema | Default |
|---|---|---|---|---|
readingListId |
The unique identifier of a reading list |
X |
String |
null |
bookshareId |
The title identifier of a book |
X |
String |
null |
Responses
| HTTP Code | Message | Datatype |
|---|---|---|
200 |
Reading List Title collection response |
|
0 |
Unexpected error |
Example HTTP request
DELETE /v2/lists/100/titles/123456 HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: api.bookshare.org
Content-Length: 15
api_key=abcdefgExample HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 2397
{
"limit" : 25,
"next" : null,
"totalResults" : 1,
"allows" : [ "POST" ],
"readingListId" : 100,
"titles" : [ {
"allows" : [ "DELETE" ],
"bookshareId" : 123456,
"title" : "Tom Sawyer",
"subtitle" : null,
"authors" : [ {
"firstName" : "Mark",
"lastName" : "Twain",
"middle" : null,
"prefix" : null,
"suffix" : null,
"links" : [ ]
} ],
"isbn13" : "9780307784056",
"synopsis" : "As part of the wonderful Collector's Library series, The Adventures of Tom Sawyer is one of the best-loved children's classics of all time.",
"seriesTitle" : null,
"seriesNumber" : null,
"copyrightDate" : "2010",
"publishDate" : null,
"formats" : [ {
"formatId" : "DAISY",
"name" : "DAISY"
}, {
"formatId" : "BRF",
"name" : "BRF"
}, {
"formatId" : "DAISY_AUDIO",
"name" : "Audio"
}, {
"formatId" : "EPUB3",
"name" : "EPUB 3"
} ],
"externalFormats" : [ ],
"titleContentType" : "",
"available" : true,
"contributors" : [ {
"name" : {
"displayName" : "Mark Twain",
"indexName" : "Twain, Mark",
"links" : [ ]
},
"type" : "author"
} ],
"composers" : null,
"lyricists" : null,
"arrangers" : null,
"translators" : null,
"editors" : null,
"instruments" : null,
"vocalParts" : null,
"languages" : [ "eng" ],
"contentWarnings" : [ ],
"categories" : [ ],
"readingAgeMinimum" : null,
"readingAgeMaximum" : null,
"lexileCode" : null,
"lexileNumber" : null,
"nimac" : false,
"numImages" : null,
"site" : "bookshare",
"titleAccessAlerts" : null,
"owner" : null,
"dateAdded" : "2015-06-10T00:00:00Z",
"ranking" : null,
"year" : null,
"month" : null,
"category" : null,
"award" : null,
"links" : [ {
"rel" : "self",
"href" : "https://api.bookshare.org/v2/titles/123456"
}, {
"rel" : "download",
"href" : "https://api.bookshare.org/v2/titles/123456/{format}"
}, {
"rel" : "coverimage",
"href" : "http://covers.bookshare.org/4538345.jpg"
}, {
"rel" : "thumbnail",
"href" : "http://covers.bookshare.org/4538345.jpg"
} ]
} ],
"links" : [ {
"rel" : "self",
"href" : "https://api.bookshare.org/v2/lists/100/titles?api_key=abcdefg"
} ]
}Example Curl request
$ curl 'https://api.bookshare.org/v2/lists/100/titles/123456' -i -X DELETE \
-d 'api_key=abcdefg'2.9.2. Get my reading lists
GET /v2/myLists
Description
Request the list of reading lists that the user is able to see. These could be private lists, shared lists, or organization lists that the user is subscribed to.
Parameters
Query Parameters
| Name | Description | Required | Schema | Default |
|---|---|---|---|---|
start |
If null or empty, it means to start at the beginning of the result set. Otherwise, it should be the value of 'next' that was returned from the previous request. |
- |
String |
null |
limit |
Maximum number of results to include. The maximum allowed is 100. |
- |
Integer |
10 |
sortOrder |
Primary sorting field. |
- |
enum [name, owner, dateUpdated] |
[name] |
direction |
Direction for sorting. |
- |
enum [asc, desc] |
[asc] |
Responses
| HTTP Code | Message | Datatype |
|---|---|---|
200 |
Reading List collection response |
|
0 |
Unexpected error |
Example HTTP request
GET /v2/myLists?api_key=abcdefg HTTP/1.1
Host: api.bookshare.orgExample HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 723
{
"limit" : 10,
"next" : null,
"totalResults" : 1,
"allows" : [ "POST" ],
"lists" : [ {
"allows" : null,
"readingListId" : 1004,
"name" : "A Reading List",
"description" : "A list of favorite books",
"access" : "private",
"owner" : "John Smith",
"titleCount" : 5,
"memberCount" : 0,
"assignedBy" : null,
"subscription" : null,
"dateUpdated" : null,
"links" : [ {
"rel" : "self",
"href" : "https://api.bookshare.org/v2/lists/1004"
}, {
"rel" : "titles",
"href" : "https://api.bookshare.org/v2/lists/1004/titles"
} ]
} ],
"links" : [ {
"rel" : "self",
"href" : "https://api.bookshare.org/v2/myLists?api_key=abcdefg"
} ]
}Example Curl request
$ curl 'https://api.bookshare.org/v2/myLists?api_key=abcdefg' -i -X GET2.9.3. Get reading list titles
GET /v2/lists/{readingListId}/titles
Description
Request the list of titles that are part of the specified reading list.
Parameters
Path Parameters
| Name | Description | Required | Schema | Default |
|---|---|---|---|---|
readingListId |
The unique identifier of a reading list. |
X |
String |
null |
Query Parameters
| Name | Description | Required | Schema | Default |
|---|---|---|---|---|
start |
If null or empty, it means to start at the beginning of the result set. Otherwise, it should be the value of 'next' that was returned from the previous request. |
- |
String |
null |
limit |
Maximum number of results to include. The maximum allowed is 100. |
- |
Integer |
10 |
sortOrder |
Primary sorting field. |
- |
enum [title, dateAddedToReadingList, author] |
[title] |
direction |
Direction for sorting. |
- |
enum [asc, desc] |
[asc] |
Responses
| HTTP Code | Message | Datatype |
|---|---|---|
200 |
Reading List Title collection response |
|
0 |
Unexpected error |
Example HTTP request
GET /v2/lists/100/titles?api_key=abcdefg HTTP/1.1
Host: api.bookshare.orgExample HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 2397
{
"limit" : 10,
"next" : null,
"totalResults" : 1,
"allows" : [ "POST" ],
"readingListId" : 100,
"titles" : [ {
"allows" : [ "DELETE" ],
"bookshareId" : 123456,
"title" : "Tom Sawyer",
"subtitle" : null,
"authors" : [ {
"firstName" : "Mark",
"lastName" : "Twain",
"middle" : null,
"prefix" : null,
"suffix" : null,
"links" : [ ]
} ],
"isbn13" : "9780307784056",
"synopsis" : "As part of the wonderful Collector's Library series, The Adventures of Tom Sawyer is one of the best-loved children's classics of all time.",
"seriesTitle" : null,
"seriesNumber" : null,
"copyrightDate" : "2010",
"publishDate" : null,
"formats" : [ {
"formatId" : "DAISY",
"name" : "DAISY"
}, {
"formatId" : "BRF",
"name" : "BRF"
}, {
"formatId" : "DAISY_AUDIO",
"name" : "Audio"
}, {
"formatId" : "EPUB3",
"name" : "EPUB 3"
} ],
"externalFormats" : [ ],
"titleContentType" : "",
"available" : true,
"contributors" : [ {
"name" : {
"displayName" : "Mark Twain",
"indexName" : "Twain, Mark",
"links" : [ ]
},
"type" : "author"
} ],
"composers" : null,
"lyricists" : null,
"arrangers" : null,
"translators" : null,
"editors" : null,
"instruments" : null,
"vocalParts" : null,
"languages" : [ "eng" ],
"contentWarnings" : [ ],
"categories" : [ ],
"readingAgeMinimum" : null,
"readingAgeMaximum" : null,
"lexileCode" : null,
"lexileNumber" : null,
"nimac" : false,
"numImages" : null,
"site" : "bookshare",
"titleAccessAlerts" : null,
"owner" : null,
"dateAdded" : "2015-06-10T00:00:00Z",
"ranking" : null,
"year" : null,
"month" : null,
"category" : null,
"award" : null,
"links" : [ {
"rel" : "self",
"href" : "https://api.bookshare.org/v2/titles/123456"
}, {
"rel" : "download",
"href" : "https://api.bookshare.org/v2/titles/123456/{format}"
}, {
"rel" : "coverimage",
"href" : "http://covers.bookshare.org/4538345.jpg"
}, {
"rel" : "thumbnail",
"href" : "http://covers.bookshare.org/4538345.jpg"
} ]
} ],
"links" : [ {
"rel" : "self",
"href" : "https://api.bookshare.org/v2/lists/100/titles?api_key=abcdefg"
} ]
}Example Curl request
$ curl 'https://api.bookshare.org/v2/lists/100/titles?api_key=abcdefg' -i -X GET2.9.4. Search for reading lists
GET /v2/lists
Description
Search for reading lists by keyword.
Parameters
Query Parameters
| Name | Description | Required | Schema | Default |
|---|---|---|---|---|
keyword |
Search string to use in searching for reading list names and descriptions. |
- |
String |
null |
access |
Access level of the list |
- |
enum [public, private] |
private |
start |
If null or empty, it means to start at the beginning of the result set. Otherwise, it should be the value of 'next' that was returned from the previous request. |
- |
String |
null |
limit |
Maximum number of results to include. The maximum allowed is 100. |
- |
Integer |
10 |
sortOrder |
Primary sorting field. |
- |
enum [name, dateUpdated] |
[name] |
direction |
Direction for sorting. |
- |
enum [asc, desc] |
[asc] |
Responses
| HTTP Code | Message | Datatype |
|---|---|---|
200 |
Reading List collection response |
|
0 |
Unexpected error |
Example HTTP request
GET /v2/lists?keyword=caldecott&access=public&api_key=abcdefg HTTP/1.1
Host: api.bookshare.orgExample HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 1166
{
"limit" : 10,
"next" : null,
"totalResults" : 1,
"allows" : null,
"lists" : [ {
"allows" : null,
"readingListId" : 194309,
"name" : "Caldecott Award Winners",
"description" : "The Caldecott Medal is awarded each year to the artist of the most distinguished American picture book for children. Bookshare is pleased to offer the Medal winner for each year as well as Honor books that are currently in our collection. #award #kids",
"access" : "public",
"owner" : "",
"titleCount" : 205,
"memberCount" : 0,
"assignedBy" : null,
"subscription" : {
"allows" : [ "PUT" ],
"enabled" : false,
"links" : [ {
"rel" : "self",
"href" : "https://api.bookshare.org/v2/lists/194309/subscription"
} ]
},
"dateUpdated" : null,
"links" : [ {
"rel" : "self",
"href" : "https://api.bookshare.org/v2/lists/194309"
}, {
"rel" : "titles",
"href" : "https://api.bookshare.org/v2/lists/194309/titles"
} ]
} ],
"links" : [ {
"rel" : "self",
"href" : "https://api.bookshare.org/v2/myLists?keyword=caldecott&access=public&api_key=abcdefg"
} ]
}Example Curl request
$ curl 'https://api.bookshare.org/v2/lists?keyword=caldecott&access=public&api_key=abcdefg' -i -X GET2.9.5. Create a reading list
POST /v2/myLists
Description
Create an empty reading list that will be owned by the current user, with the properties provided.
Parameters
Form Parameters
| Name | Description | Required | Schema | Default |
|---|---|---|---|---|
name |
The name of the reading list |
X |
String |
null |
access |
Visibility of the list |
X |
enum [private, shared, org] |
null |
description |
The description of the reading list |
- |
String |
null |
Responses
| HTTP Code | Message | Datatype |
|---|---|---|
200 |
Reading List response |
|
0 |
Unexpected error |
Example HTTP request
POST /v2/myLists HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: api.bookshare.org
Content-Length: 87
name=A+Reading+List&description=A+list+of+favorite+books&access=private&api_key=abcdefgExample HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 474
{
"allows" : null,
"readingListId" : 1004,
"name" : "A Reading List",
"description" : "A list of favorite books",
"access" : "private",
"owner" : "John Smith",
"titleCount" : 5,
"memberCount" : 0,
"assignedBy" : null,
"subscription" : null,
"dateUpdated" : null,
"links" : [ {
"rel" : "self",
"href" : "https://api.bookshare.org/v2/lists/1004"
}, {
"rel" : "titles",
"href" : "https://api.bookshare.org/v2/lists/1004/titles"
} ]
}Example Curl request
$ curl 'https://api.bookshare.org/v2/myLists' -i -X POST \
-d 'name=A+Reading+List&description=A+list+of+favorite+books&access=private&api_key=abcdefg'2.9.6. Add a title to a reading list
POST /v2/lists/{readingListId}/titles
Description
Add a title to the specified reading list. The reading list must be one that the user created, or that they have rights to as an organization sponsor or membership assistant.
Parameters
Path Parameters
| Name | Description | Required | Schema | Default |
|---|---|---|---|---|
readingListId |
The unique identifier of a reading list |
X |
String |
null |
Form Parameters
| Name | Description | Required | Schema | Default |
|---|---|---|---|---|
bookshareId |
The title identifier of a book |
X |
String |
null |
Responses
| HTTP Code | Message | Datatype |
|---|---|---|
200 |
Reading List Title collection response |
|
0 |
Unexpected error |
Example HTTP request
POST /v2/lists/100/titles HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Accept: application/json
Host: api.bookshare.org
Content-Length: 34
bookshareId=123456&api_key=abcdefgExample HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 2397
{
"limit" : 25,
"next" : null,
"totalResults" : 1,
"allows" : [ "POST" ],
"readingListId" : 100,
"titles" : [ {
"allows" : [ "DELETE" ],
"bookshareId" : 123456,
"title" : "Tom Sawyer",
"subtitle" : null,
"authors" : [ {
"firstName" : "Mark",
"lastName" : "Twain",
"middle" : null,
"prefix" : null,
"suffix" : null,
"links" : [ ]
} ],
"isbn13" : "9780307784056",
"synopsis" : "As part of the wonderful Collector's Library series, The Adventures of Tom Sawyer is one of the best-loved children's classics of all time.",
"seriesTitle" : null,
"seriesNumber" : null,
"copyrightDate" : "2010",
"publishDate" : null,
"formats" : [ {
"formatId" : "DAISY",
"name" : "DAISY"
}, {
"formatId" : "BRF",
"name" : "BRF"
}, {
"formatId" : "DAISY_AUDIO",
"name" : "Audio"
}, {
"formatId" : "EPUB3",
"name" : "EPUB 3"
} ],
"externalFormats" : [ ],
"titleContentType" : "",
"available" : true,
"contributors" : [ {
"name" : {
"displayName" : "Mark Twain",
"indexName" : "Twain, Mark",
"links" : [ ]
},
"type" : "author"
} ],
"composers" : null,
"lyricists" : null,
"arrangers" : null,
"translators" : null,
"editors" : null,
"instruments" : null,
"vocalParts" : null,
"languages" : [ "eng" ],
"contentWarnings" : [ ],
"categories" : [ ],
"readingAgeMinimum" : null,
"readingAgeMaximum" : null,
"lexileCode" : null,
"lexileNumber" : null,
"nimac" : false,
"numImages" : null,
"site" : "bookshare",
"titleAccessAlerts" : null,
"owner" : null,
"dateAdded" : "2015-06-10T00:00:00Z",
"ranking" : null,
"year" : null,
"month" : null,
"category" : null,
"award" : null,
"links" : [ {
"rel" : "self",
"href" : "https://api.bookshare.org/v2/titles/123456"
}, {
"rel" : "download",
"href" : "https://api.bookshare.org/v2/titles/123456/{format}"
}, {
"rel" : "coverimage",
"href" : "http://covers.bookshare.org/4538345.jpg"
}, {
"rel" : "thumbnail",
"href" : "http://covers.bookshare.org/4538345.jpg"
} ]
} ],
"links" : [ {
"rel" : "self",
"href" : "https://api.bookshare.org/v2/lists/100/titles?api_key=abcdefg"
} ]
}Example Curl request
$ curl 'https://api.bookshare.org/v2/lists/100/titles' -i -X POST \
-H 'Accept: application/json' \
-d 'bookshareId=123456&api_key=abcdefg'2.9.7. Edit reading list metadata
PUT /v2/lists/{readingListId}
Description
Edit the metadata of an existing reading list.
Parameters
Path Parameters
| Name | Description | Required | Schema | Default |
|---|---|---|---|---|
readingListId |
The unique identifier of a reading list |
X |
String |
null |
Form Parameters
| Name | Description | Required | Schema | Default |
|---|---|---|---|---|
name |
The name of the reading list |
- |
String |
null |
description |
The description of the reading list |
- |
String |
null |
access |
Visibility of the list |
- |
enum [private, shared, org] |
null |
Responses
| HTTP Code | Message | Datatype |
|---|---|---|
200 |
Reading List response |
|
0 |
Unexpected error |
Example HTTP request
PUT /v2/lists/100 HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: api.bookshare.org
Content-Length: 78
name=edited+name&description=edited+description&access=private&api_key=abcdefgExample HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 467
{
"allows" : [ "PUT" ],
"readingListId" : 100,
"name" : "edited name",
"description" : "edited description",
"access" : "private",
"owner" : "John Smith",
"titleCount" : 5,
"memberCount" : 0,
"subscriberCount" : 0,
"assignedBy" : null,
"dateUpdated" : null,
"links" : [ {
"rel" : "self",
"href" : "https://api.bookshare.org/v2/lists/100"
}, {
"rel" : "titles",
"href" : "https://api.bookshare.org/v2/lists/100/titles"
} ]
}Example Curl request
$ curl 'https://api.bookshare.org/v2/lists/100' -i -X PUT \
-d 'name=edited+name&description=edited+description&access=private&api_key=abcdefg'2.9.8. Subscribe to or unsubscribe from a reading list
PUT /v2/myLists/{readingListId}/subscription
Description
Subscribe to or unsubscribe from a reading list that the user does not own.
Parameters
Path Parameters
| Name | Description | Required | Schema | Default |
|---|---|---|---|---|
readingListId |
The unique identifier of a reading list |
X |
String |
null |
Form Parameters
| Name | Description | Required | Schema | Default |
|---|---|---|---|---|
enabled |
If true, subscribes the user to the reading list, false unsubscribes the user. |
X |
Boolean |
null |
Responses
| HTTP Code | Message | Datatype |
|---|---|---|
200 |
Reading List user view |
|
0 |
Unexpected error |
Example HTTP request
PUT /v2/myLists/100/subscription HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: api.bookshare.org
Content-Length: 28
enabled=true&api_key=abcdefgExample HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 646
{
"allows" : [ "PUT" ],
"readingListId" : 100,
"name" : "My Reading List",
"description" : "A list of my favorite books",
"access" : "private",
"owner" : "John Smith",
"titleCount" : 5,
"memberCount" : 0,
"assignedBy" : null,
"subscription" : {
"allows" : [ "PUT" ],
"enabled" : true,
"links" : [ {
"rel" : "self",
"href" : "https://api.bookshare.org/v2/lists/100/subscription"
} ]
},
"dateUpdated" : null,
"links" : [ {
"rel" : "self",
"href" : "https://api.bookshare.org/v2/lists/100"
}, {
"rel" : "titles",
"href" : "https://api.bookshare.org/v2/lists/100/titles"
} ]
}Example Curl request
$ curl 'https://api.bookshare.org/v2/myLists/100/subscription' -i -X PUT \
-d 'enabled=true&api_key=abcdefg'2.10. Recommendations
Recommendations represent titles that Bookshare recommends to a user based on their reading history.
2.10.1. Get my recommended titles
GET /v2/myRecommendations
Description
Get recommended titles for the requesting user.
Parameters
Query Parameters
| Name | Description | Required | Schema | Default |
|---|---|---|---|---|
start |
If null or empty, it means to start at the beginning of the result set. Otherwise, it should be the value of 'next' that was returned from the previous request. |
- |
String |
null |
limit |
Maximum number of results to include. The maximum allowed is 100. |
- |
Integer |
10 |
Responses
| HTTP Code | Message | Datatype |
|---|---|---|
200 |
My Recommendations response |
|
0 |
Unexpected error |
Example HTTP request
GET /v2/myRecommendations?api_key=abcdefg HTTP/1.1
Host: api.bookshare.orgExample HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 2619
{
"limit" : 10,
"next" : null,
"totalResults" : 1,
"recommendedTitles" : [ {
"allows" : null,
"bookshareId" : 101175,
"title" : "Little House on the Prairie",
"subtitle" : null,
"authors" : [ {
"firstName" : "Laura",
"lastName" : "Wilder",
"middle" : "Ingalls",
"prefix" : "",
"suffix" : "",
"links" : [ ]
} ],
"isbn13" : "9780060264451",
"synopsis" : "The adventures continue for Laura Ingalls and her family as they leave their little house in the Big Woods of Wisconsin and set out for Kansas.",
"seriesTitle" : "Little House",
"seriesNumber" : "3",
"copyrightDate" : "1970",
"publishDate" : "2009-07-24T00:00:00Z",
"formats" : [ {
"formatId" : "BRF",
"name" : "BRF"
}, {
"formatId" : "DAISY",
"name" : "DAISY"
}, {
"formatId" : "EPUB3",
"name" : "EPUB 3"
}, {
"formatId" : "DAISY_2_AUDIO",
"name" : "DAISY 2 Audio"
} ],
"externalFormats" : [ ],
"titleContentType" : "text",
"available" : true,
"contributors" : [ {
"name" : {
"displayName" : "Laura Ingalls Wilder",
"indexName" : null,
"links" : [ ]
},
"type" : "author"
} ],
"composers" : [ ],
"lyricists" : [ ],
"arrangers" : [ ],
"translators" : [ ],
"editors" : null,
"instruments" : null,
"vocalParts" : null,
"languages" : [ "eng" ],
"contentWarnings" : [ ],
"categories" : [ {
"name" : "Literature and Fiction",
"description" : "Literature and Fiction",
"categoryType" : "Bookshare",
"code" : null,
"links" : [ ]
}, {
"name" : "JUVENILE FICTION / General",
"description" : "JUVENILE FICTION / General",
"categoryType" : "BISAC",
"code" : "JUV016011",
"links" : [ ]
} ],
"readingAgeMinimum" : 8,
"readingAgeMaximum" : 12,
"lexileCode" : null,
"lexileNumber" : null,
"nimac" : false,
"numImages" : 5,
"site" : "bookshare",
"titleAccessAlerts" : null,
"owner" : null,
"links" : [ {
"rel" : "self",
"href" : "https://api.bookshare.org/v2/titles/101175"
}, {
"rel" : "download",
"href" : "https://api.bookshare.org/v2/titles/101175/{format}"
}, {
"rel" : "coverimage",
"href" : "http://covers.bookshare.org/4538345.jpg"
}, {
"rel" : "thumbnail",
"href" : "http://covers.bookshare.org/4538345.jpg"
} ]
} ],
"links" : [ {
"rel" : "self",
"href" : "https://api.bookshare.org/v2/myRecommendations?api_key=abcdefg"
} ]
}Example Curl request
$ curl 'https://api.bookshare.org/v2/myRecommendations?api_key=abcdefg' -i -X GET2.11. Titles
A title represents a unique entry in the Bookshare collection. They are available to users based on a combination of the characteristics of the user (their subscription, their address, their age, etc) and the characteristics of the title (its distribution area, whether it is copyrighted, etc). Users can request a metadata representation of almost any title, but they can only request a file download if the user and title characteristics allow, and if the requested format is available for the particular title. The title metadata resource is where you will find links to the specific file format resources that are available for each specific title.
2.11.1. Category listing
GET /v2/categories
Description
Get a list of categories defined on the collection, with a count of titles associated with each category. The count reflects the number of titles that the current user would have access to. The categories include only those with at least one title association.
Parameters
Query Parameters
| Name | Description | Required | Schema | Default |
|---|---|---|---|---|
start |
If null or empty, it means to start at the beginning of the result set. Otherwise, it should be the value of 'next' that was returned from the previous request. |
- |
String |
null |
limit |
Maximum number of results to include. The maximum allowed is 100. |
- |
Integer |
100 |
Responses
| HTTP Code | Message | Datatype |
|---|---|---|
200 |
Categories list response |
|
0 |
Unexpected error |
Example HTTP request
GET /v2/categories?limit=5&api_key=abcdefg HTTP/1.1
Host: api.bookshare.orgExample HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 1524
{
"limit" : 5,
"next" : "abcde",
"totalResults" : 49,
"categories" : [ {
"name" : "Animals",
"description" : "Animals",
"titleCount" : 15891,
"links" : [ {
"rel" : "search",
"href" : "https://api.bookshare.org/v2/titles?categories=Animals"
} ]
}, {
"name" : "Art and Architecture",
"description" : "Art and Architecture",
"titleCount" : 16317,
"links" : [ {
"rel" : "search",
"href" : "https://api.bookshare.org/v2/titles?categories=Art and Architecture"
} ]
}, {
"name" : "Biographies and Memoirs",
"description" : "Biographies and Memoirs",
"titleCount" : 35276,
"links" : [ {
"rel" : "search",
"href" : "https://api.bookshare.org/v2/titles?categories=Biographies and Memoirs"
} ]
}, {
"name" : "Business and Finance",
"description" : "Business and Finance",
"titleCount" : 51115,
"links" : [ {
"rel" : "search",
"href" : "https://api.bookshare.org/v2/titles?categories=Business and Finance"
} ]
}, {
"name" : "Children's Books",
"description" : "Children's Books",
"titleCount" : 59871,
"links" : [ {
"rel" : "search",
"href" : "https://api.bookshare.org/v2/titles?categories=Children's Books"
} ]
} ],
"links" : [ {
"rel" : "self",
"href" : "https://api.bookshare.org/v2/categories?limit=5&api_key=abcdefg"
}, {
"rel" : "next",
"href" : "https://api.bookshare.org/v2/categories?limit=5&api_key=abcdefg&start=abcde"
} ]
}Example Curl request
$ curl 'https://api.bookshare.org/v2/categories?limit=5&api_key=abcdefg' -i -X GET2.11.2. Get a list of BISAC category codes
GET /v2/bisacCodes
Description
Get a list of BISAC category codes that are used by the system. The listing can be filtered by matches against partial code or description values. The BISAC codes are maintained by the Book Industry Study Group and described on their website BISAC code list.
Parameters
Query Parameters
| Name | Description | Required | Schema | Default |
|---|---|---|---|---|
codeStartsWith |
Search for codes that start with this string, case insensitive. This parameter can only be used if not using the 'descriptionStartsWith' parameter. |
- |
String |
null |
descriptionStartsWith |
Search for codes that have a description that starts with this string, case insensitive. This parameter can only be used if not using the 'codeStartsWith' parameter. |
- |
String |
null |
start |
If null or empty, it means to start at the beginning of the result set. Otherwise, it should be the value of 'next' that was returned from the previous request. |
- |
String |
null |
limit |
Maximum number of results to include. The maximum allowed is 100. |
- |
Integer |
100 |
Responses
| HTTP Code | Message | Datatype |
|---|---|---|
200 |
BISAC Code collection response |
|
0 |
Unexpected error |
Example HTTP request
GET /v2/bisacCodes?limit=1&api_key=abcdefg HTTP/1.1
Host: api.bookshare.orgExample HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 192
{
"limit" : 1,
"next" : "abcde",
"totalResults" : 4907,
"bisacCodes" : [ {
"code" : "FIC000000",
"description" : "FICTION / General",
"links" : [ ]
} ],
"links" : [ ]
}Example Curl request
$ curl 'https://api.bookshare.org/v2/bisacCodes?limit=1&api_key=abcdefg' -i -X GET2.11.3. Download a title file resource
GET /v2/titles/{bookshareId}/{format}/resources/{resourceId}
Description
Download a single title file resource that is part of a title artifact. Note: this URL will be constructed by the system, and appear in the title file resources response.
Parameters
Path Parameters
| Name | Description | Required | Schema | Default |
|---|---|---|---|---|
bookshareId |
Unique identifier of a title |
X |
String |
null |
format |
The format of the title artifact |
X |
enum [DAISY, DAISY_AUDIO, DAISY_2_AUDIO, BRF, EPUB3, PDF, DOCX] |
null |
resourceId |
Unique identifier of the title file resource |
X |
String |
null |
Query Parameters
| Name | Description | Required | Schema | Default |
|---|---|---|---|---|
speed |
Playback speed rate, for mp3 file only. Numerical value from 0.5 to 3.5, as a multiplier, in increments of 0.05. If not included then the default speed is 1. |
- |
Float |
null |
Responses
| HTTP Code | Message | Datatype |
|---|---|---|
302 |
Redirect to the header location |
|
0 |
Unexpected error |
Example HTTP request
GET /v2/titles/1343455/DAISY/resources/34444?api_key=abcdefg HTTP/1.1
Host: api.bookshare.orgExample HTTP response
HTTP/1.1 302 Found
Location: http://exampleurl.com
Content-Type: application/json
Content-Length: 69
{
"key" : "AVAILABLE",
"messages" : [ "http://exampleurl.com" ]
}Example Curl request
$ curl 'https://api.bookshare.org/v2/titles/1343455/DAISY/resources/34444?api_key=abcdefg' -i -X GET2.11.4. Get a list of title file resources
GET /v2/titles/{bookshareId}/{format}/resources
Description
Ask for a list of title file resources for the artifact of the given format. This will give a list of information about each file that makes up the artifact, including a link to retrieve each file. MP3-compatible reading systems can use the DAISY_AUDIO format to get references to .mp3 files.
Parameters
Path Parameters
| Name | Description | Required | Schema | Default |
|---|---|---|---|---|
bookshareId |
Unique identifier of a title |
X |
String |
null |
format |
The format of the title artifact |
X |
enum [DAISY, DAISY_AUDIO, DAISY_2_AUDIO, BRF, EPUB3, PDF, DOCX] |
null |
Query Parameters
| Name | Description | Required | Schema | Default |
|---|---|---|---|---|
limit |
Maximum number of file resources to list. Maximum allowed is 100. |
- |
Integer |
10 |
start |
If null or empty, it means to start at the beginning of the result set. Otherwise, it should be the value of 'next' that was returned from the previous request. |
- |
String |
null |
Responses
| HTTP Code | Message | Datatype |
|---|---|---|
200 |
Title file resource collection response |
|
0 |
Unexpected error |
Example HTTP request
GET /v2/titles/1343455/DAISY_2_AUDIO/resources?api_key=abcdefg HTTP/1.1
Host: api.bookshare.orgExample HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 449
{
"limit" : 10,
"next" : null,
"totalResults" : 1,
"titleFileResources" : [ {
"mimeType" : "image/jpeg",
"size" : 10000000,
"localURI" : "./images/sun001.jpg",
"lastModifiedDate" : "2018-09-01T00:00:00Z",
"links" : [ {
"rel" : "self",
"href" : "http://exampleurl.com"
} ]
} ],
"links" : [ {
"rel" : "self",
"href" : "https://api.bookshare.org/v2/titles/1343455/DAISY_2_AUDIO/resources"
} ]
}Example Curl request
$ curl 'https://api.bookshare.org/v2/titles/1343455/DAISY_2_AUDIO/resources?api_key=abcdefg' -i -X GET2.11.5. Live title count
GET /v2/titles/count
Description
Get a count of the live titles available in the collection which the user has access to. The boundaries of that can be adjusted to include titles shared from other partners or not, or to view the collection from a country other than that of the current user.
Parameters
Query Parameters
| Name | Description | Required | Schema | Default |
|---|---|---|---|---|
includeShared |
Include titles that have been marked as shared from other partner sites. The default is to only count titles associated with the site of the requesting user. |
- |
Boolean |
null |
country |
Limit count to titles available in the given country. The value should be a two-character ISO 3166 alpha-2 country code. If nothing is specified, then the user’s country will be used |
- |
String |
null |
Example HTTP request
GET /v2/titles/count?includeShared=true&country=US&api_key=abcdefg HTTP/1.1
Host: api.bookshare.orgExample HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 6
503246Example Curl request
$ curl 'https://api.bookshare.org/v2/titles/count?includeShared=true&country=US&api_key=abcdefg' -i -X GET2.11.6. Download a title
GET /v2/titles/{bookshareId}/{format}
Description
Ask to download a title in a specific format. This will request a package of a title artifact, which will be fingerprinted and watermarked to indicate it’s delivery to either the current user, or the 'forUser' if that is specified. If the package is not available immediately, requests to this endpoint will simply return a status to acknowledge receipt. Subsequent requests will eventually return a reference to the delivery file for the given format (ZIP, EPUB, PDF, etc). End users with MP3-compatible reading systems can get .mp3 files from a DAISY_AUDIO package. The 'forUser' parameter allows organization sponsors to download on behalf of their members. The values for the 'forUser' parameter can be found by asking for the sponsor’s organization member list.
Parameters
Path Parameters
| Name | Description | Required | Schema | Default |
|---|---|---|---|---|
bookshareId |
Unique identifier of a title |
X |
String |
null |
format |
The format of the title artifact |
X |
enum [DAISY, DAISY_AUDIO, DAISY_2_AUDIO, BRF, EPUB3, PDF, DOCX] |
null |
Query Parameters
| Name | Description | Required | Schema | Default |
|---|---|---|---|---|
forUser |
If the download is on behalf of a member, the member identifier |
- |
String |
null |
Responses
| HTTP Code | Message | Datatype |
|---|---|---|
202 |
Request has been received, and will be processed. |
|
302 |
Redirect to the header location |
|
429 |
Too many requests. The request can be retried later. |
|
0 |
Unexpected error |
Example HTTP request
GET /v2/titles/123456/DAISY?api_key=abcdefg HTTP/1.1
Host: api.bookshare.orgExample HTTP response
HTTP/1.1 202 Accepted
Cache-Control: max-age=60
Content-Type: application/json
Content-Length: 78
{
"key" : "SUBMITTED",
"messages" : [ "Packaging requested for 123456" ]
}Example Curl request
$ curl 'https://api.bookshare.org/v2/titles/123456/DAISY?api_key=abcdefg' -i -X GETExample response when the title package is ready
If a request returns a 202 status, you should continue to call this endpoint at intervals (e.g. every 10 seconds) until you get a response that points to the finished package.
HTTP/1.1 302 Found
Content-Type: application/json;charset=UTF-8
Location: https://download-cache.bookshare.org/some/path/to/Tom_Sawyer_Sample_User_Daisy.zip?foo=blah&bar=baz
{
"key" : "COMPLETED",
"messages" : [ "https://download-cache.bookshare.org/some/path/to/Tom_Sawyer_Sample_User_Daisy.zip?foo=blah&bar=baz" ],
"links" : [ ]
}Example HTTP request to download as a sponsor for a student
The simplest request for this resource endpoint will package a title for the authenticated user who is making the call. If the user is a sponsor at an organization such as a school, and is requesting this resource on behalf of a student member, then you should add the student’s identifier in the 'forUser' parameter. The identifiers for members of an organization can be found in the Organization Member List resource.
GET /v2/titles/123456/DAISY?forUser=abcd1234efgh5678&api_key=abcdefg HTTP/1.1
Host: api.bookshare.org2.11.7. Get title metadata
GET /v2/titles/{bookshareId}
Description
Ask for a title’s metadata. This includes title, author, ISBN and other properties.
Parameters
Path Parameters
| Name | Description | Required | Schema | Default |
|---|---|---|---|---|
bookshareId |
Unique identifier of a title |
X |
String |
null |
Responses
| HTTP Code | Message | Datatype |
|---|---|---|
200 |
Title metadata response |
|
0 |
Unexpected error |
Example HTTP request
GET /v2/titles/101175?api_key=abcdefg HTTP/1.1
Host: api.bookshare.orgExample HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 5497
{
"allows" : null,
"bookshareId" : 101175,
"title" : "Little House on the Prairie",
"subtitle" : null,
"authors" : [ {
"firstName" : "Laura",
"lastName" : "Wilder",
"middle" : "Ingalls",
"prefix" : null,
"suffix" : null,
"links" : [ ]
} ],
"isbn13" : "9780060264451",
"synopsis" : "The adventures continue for Laura Ingalls and her family as they leave their little house in the Big Woods of Wisconsin and set out for Kansas.",
"seriesTitle" : "Little House",
"seriesNumber" : "3",
"copyrightDate" : "1970",
"publishDate" : "2009-07-24T00:00:00Z",
"formats" : [ {
"formatId" : "DAISY",
"name" : "DAISY"
}, {
"formatId" : "BRF",
"name" : "BRF"
}, {
"formatId" : "DAISY_AUDIO",
"name" : "Audio"
}, {
"formatId" : "EPUB3",
"name" : "EPUB 3"
} ],
"externalFormats" : [ ],
"titleContentType" : "text",
"available" : true,
"contributors" : [ {
"name" : {
"displayName" : "Laura Ingalls Wilder",
"indexName" : "Wilder, Laura Ingalls",
"links" : [ ]
},
"type" : "author"
} ],
"composers" : null,
"lyricists" : null,
"arrangers" : null,
"translators" : null,
"editors" : null,
"instruments" : null,
"vocalParts" : null,
"languages" : [ "eng" ],
"contentWarnings" : [ ],
"categories" : [ {
"name" : "Literature and Fiction",
"description" : "Literature and Fiction",
"categoryType" : "Bookshare",
"code" : null,
"links" : [ ]
}, {
"name" : "JUVENILE FICTION / General",
"description" : "JUVENILE FICTION / General",
"categoryType" : "BISAC",
"code" : "JUV016011",
"links" : [ ]
} ],
"readingAgeMinimum" : 8,
"readingAgeMaximum" : 12,
"lexileCode" : "HL",
"lexileNumber" : "760L",
"nimac" : false,
"numImages" : 5,
"site" : "bookshare",
"titleAccessAlerts" : null,
"owner" : null,
"adultContent" : false,
"usageRestriction" : {
"usageRestrictionId" : 2,
"restrictionCode" : "copyright",
"name" : "Copyright"
},
"grades" : [ {
"gradeId" : 4,
"gradeCode" : "3",
"name" : "Third grade",
"links" : [ ]
}, {
"gradeId" : 5,
"gradeCode" : "4",
"name" : "Fourth grade",
"links" : [ ]
}, {
"gradeId" : 6,
"gradeCode" : "5",
"name" : "Fifth grade",
"links" : [ ]
}, {
"gradeId" : 7,
"gradeCode" : "6",
"name" : "Sixth grade",
"links" : [ ]
} ],
"countries" : [ "US", "CA" ],
"originCountry" : null,
"numPages" : 349,
"copyright" : "Roger L. McBride",
"copyrightHolder" : "Roger L. McBride",
"publisher" : "HarperCollins Publishers",
"withdrawalDate" : null,
"replacementId" : null,
"relatedIsbns" : null,
"seriesSubtitle" : null,
"allowRecommend" : null,
"externalCategoryCode" : null,
"artifacts" : [ {
"format" : "DAISY_2_AUDIO",
"globalBookServiceId" : "1001",
"producer" : "General Producer",
"supplier" : "Acme Supplier",
"fundingSource" : "Funder A",
"duration" : "PT5H",
"narrator" : {
"name" : "Susan",
"gender" : "female",
"type" : "tts"
},
"brailleCode" : "",
"brailleGrade" : "",
"brailleType" : "",
"brailleMusicScoreLayout" : "",
"numberOfVolumes" : null,
"externalIdentifierCode" : null,
"transcriber" : null,
"accessibility" : {
"accessibilitySummary" : null,
"accessibilityCertifications" : [ ],
"accessibilityConformances" : [ ],
"accessibilityFeatures" : [ ],
"accessibilityHazards" : [ ],
"accessModes" : [ ],
"accessModesSufficient" : [ ]
},
"dateAdded" : "2018-09-01T00:00:00Z"
}, {
"format" : "EPUB3",
"globalBookServiceId" : null,
"producer" : null,
"supplier" : null,
"fundingSource" : null,
"duration" : null,
"narrator" : null,
"brailleCode" : null,
"brailleGrade" : null,
"brailleType" : null,
"brailleMusicScoreLayout" : null,
"numberOfVolumes" : null,
"externalIdentifierCode" : null,
"transcriber" : null,
"accessibility" : {
"accessibilitySummary" : "This publication conforms to WCAG 2.1 Level AAA. It contains image descriptions and no hazards.",
"accessibilityCertifications" : [ {
"certifierReport" : "bookshare.org/fakereport",
"certifiedBy" : "DAISY OK",
"certifierCredentials" : "Acme corporation credentials"
} ],
"accessibilityConformances" : [ "WCAG 2.1", "Level AAA" ],
"accessibilityFeatures" : [ {
"accessibilityFeature" : "alternativeText",
"accessibilityFeatureDescription" : null
} ],
"accessibilityHazards" : [ "none" ],
"accessModes" : [ "visual", "textual" ],
"accessModesSufficient" : [ "textual", "textual, visual" ]
},
"dateAdded" : null
} ],
"edition" : null,
"opus" : null,
"movementNumber" : null,
"movementTitle" : null,
"key" : null,
"musicScoreType" : null,
"hasChordSymbols" : false,
"marrakeshAvailable" : null,
"marrakeshPODException" : false,
"notes" : null,
"status" : "live",
"links" : [ {
"rel" : "self",
"href" : "https://api.bookshare.org/v2/titles/101175"
}, {
"rel" : "download",
"href" : "https://api.bookshare.org/v2/titles/101175/{format}"
}, {
"rel" : "coverimage",
"href" : "https://covers.bookshare.org/title_instance/efe/medium/1041744.jpg"
}, {
"rel" : "thumbnail",
"href" : "https://covers.bookshare.org/title_instance/efe/small/1041744.jpg"
} ]
}Example Curl request
$ curl 'https://api.bookshare.org/v2/titles/101175?api_key=abcdefg' -i -X GET2.11.8. Search for titles
GET /v2/titles
Description
To discover titles in the collection, you can ask for the collection of title resources, filtered by a number of criteria such as title, author, ISBN, keyword or country availability. A search on keyword will search the title, author, and ISBN fields for that keyword. Keyword searches may be further filtered by an author filter parameter, but any other parameters will be ignored. The result will be a collection of title metadata resources, with a paging token if the results are more than the paging limit.
Parameters
Query Parameters
| Name | Description | Required | Schema | Default |
|---|---|---|---|---|
title |
Search string to use in searching for matching titles. |
- |
String |
null |
author |
Search string to use in searching for matching authors. Multiple authors can be searched with this parameter, separated by spaces. |
- |
String |
null |
authorFilter |
Limit the results for keyword searches to those with an author name that matches the given value. |
- |
String |
null |
narrator |
Search string to use in searching for matching narrators. Multiple narrators can be searched with this parameter, separated by spaces. |
- |
String |
null |
composer |
Search string to use in searching for matching composers. Multiple composers can be searched with this parameter, separated by spaces. |
- |
String |
null |
keyword |
Search string to use for a quick search. The search string will be matched against title, any contributor, and ISBN. If a keyword is provided, an author filter parameter can be specified to further filter results. Any other parameters will be ignored. |
- |
String |
null |
isbn |
Search string to use to search for matching ISBNs. Spaces and dashes will be stripped. Invalid ISBNs will return an error from the search. |
- |
String |
null |
categories |
Bookshare categories, each sent as an individual parameter. For choices, see the category listing endpoint. |
- |
String, multi |
null |
includedBisacCodes |
BISAC codes, each sent as an individual parameter. For choices, see the get a list of BISAC category codes endpoint. |
- |
String, multi |
null |
excludedBisacCodes |
BISAC codes, each sent as an individual parameter. For choices, see the get a list of BISAC category codes endpoint. |
- |
String, multi |
null |
includedBisacHeadings |
BISAC headings, each sent as an individual parameter. For choices, see the get a list of BISAC category codes endpoint. |
- |
String, multi |
null |
excludedBisacHeadings |
BISAC headings, each sent as an individual parameter. For choices, see the get a list of BISAC category codes endpoint. |
- |
String, multi |
null |
language |
Language code to use to match the language of the periodical. The value should be a three-character ISO 639-2 alpha-3 language code |
- |
String |
null |
country |
Limit results to those available in the given country. The value should be a two-character ISO 3166 alpha-2 country code. |
- |
String |
null |
originCountry |
Limit results to those that originated from the given country. The value should be a two-character ISO 3166 alpha-2 country code. |
- |
String |
null |
format |
Deprecated (use formats) - Limit results to those with artifacts of the given format. |
- |
enum [DAISY, DAISY_AUDIO, DAISY_2_AUDIO, BRF, EPUB3, PDF, DOCX] |
null |
formats |
Limit results to those with artifacts of the given formats, each sent as an individual parameter. |
- |
enum [DAISY, DAISY_AUDIO, DAISY_2_AUDIO, BRF, EPUB3, PDF, DOCX], multi |
null |
externalFormats |
Limit results to those with artifacts of the given external formats, each sent as an individual parameter. |
- |
enum [MUSIC_BRAILLE, HARDCOPY_BRAILLE, PRINT_BRAILLE, FEELIX_KIT], multi |
null |
narratorType |
Limit results to those with audio artifacts that are voiced by the given narrator type. If format is not also specified, it will default to search for DAISY_AUDIO or DAISY_2_AUDIO. |
- |
enum [human, tts] |
null |
brailleType |
Limit results to those with BRF artifacts that were created in the given way. If format is not also specified, it will default to search for BRF. |
- |
enum [transcribed, automated] |
null |
readingAge |
Limit results to those with a specific reading age. |
- |
Integer |
null |
excludedContentWarnings |
Limit results to titles that do not match any of the given content warning flags. |
- |
enum [contentWarning, sex, violence, drugs, language, intolerance, adult, unrated], multi |
null |
includedContentWarnings |
Limit results to titles that match at least one of the given content warning flags. |
- |
enum [contentWarning, sex, violence, drugs, language, intolerance, adult, unrated], multi |
null |
externalIdentifierCode |
Limit results to those with a specific external identifier code. This code is most often found on titles associated with sites other than Bookshare. |
- |
String |
null |
maxDuration |
Limit results to those that have a duration less than the maxmimum duration in ISO 8601 duration format (PTnHnMnS). For example, 'PT5H' would represent 5 hours. |
- |
String |
null |
titleContentType |
Limit results to those of the given content type. |
- |
enum [text, musicScore] |
null |
start |
If null or empty, it means to start at the beginning of the result set. Otherwise, it should be the value of 'next' that was returned from the previous request. |
- |
String |
null |
excludeGlobalCollection |
Limit results to only copyrighted titles owned by the user’s site. |
- |
Boolean |
false |
limit |
Maximum number of results to include. The maximum allowed is 100. |
- |
Integer |
10 |
sortOrder |
Primary sorting field. |
- |
enum [relevance, title, author, dateAdded, copyrightDate] |
[relevance] |
direction |
Direction for sorting. |
- |
enum [asc, desc] |
[asc] |
Responses
| HTTP Code | Message | Datatype |
|---|---|---|
200 |
Title metadata collection response. |
|
0 |
Unexpected error |
Example HTTP request
GET /v2/titles?country=CA&limit=1&title=Tom+Sawyer&author=Mark+Twain&isbn=9781551998121&categories=Literature+and+Fiction&categories=Children%27s+Books&sortOrder=dateAdded&direction=desc&api_key=abcdefg HTTP/1.1
Host: api.bookshare.orgExample HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 3006
{
"limit" : 1,
"next" : "abcde",
"totalResults" : 450450,
"allows" : [ "POST" ],
"titles" : [ {
"allows" : null,
"bookshareId" : 1041744,
"title" : "The Adventures of Tom Sawyer",
"subtitle" : null,
"authors" : [ {
"firstName" : "Mark",
"lastName" : "Twain",
"middle" : "",
"prefix" : "",
"suffix" : "",
"links" : [ ]
} ],
"isbn13" : "9781551998121",
"synopsis" : "The classic boy-hero of American literature.",
"seriesTitle" : null,
"seriesNumber" : null,
"copyrightDate" : null,
"publishDate" : "2015-05-08T00:00:00Z",
"formats" : [ {
"formatId" : "BRF",
"name" : "BRF"
}, {
"formatId" : "DAISY",
"name" : "DAISY"
}, {
"formatId" : "EPUB3",
"name" : "EPUB 3"
} ],
"externalFormats" : [ ],
"titleContentType" : "text",
"available" : true,
"contributors" : [ {
"name" : {
"displayName" : "Mark Twain",
"indexName" : null,
"links" : [ ]
},
"type" : "author"
} ],
"composers" : [ ],
"lyricists" : [ ],
"arrangers" : [ ],
"translators" : [ ],
"editors" : null,
"instruments" : null,
"vocalParts" : null,
"languages" : [ "eng" ],
"contentWarnings" : [ ],
"categories" : [ {
"name" : "Literature and Fiction",
"description" : "Literature and Fiction",
"categoryType" : "Bookshare",
"code" : null,
"links" : [ ]
}, {
"name" : "FICTION / Action & Adventure",
"description" : "FICTION / Action & Adventure",
"categoryType" : "BISAC",
"code" : "FIC002000",
"links" : [ ]
} ],
"readingAgeMinimum" : 10,
"readingAgeMaximum" : 16,
"lexileCode" : null,
"lexileNumber" : null,
"nimac" : false,
"numImages" : 5,
"site" : "bookshare",
"titleAccessAlerts" : null,
"owner" : null,
"links" : [ {
"rel" : "self",
"href" : "https://api.bookshare.org/v2/titles/1041744"
}, {
"rel" : "download",
"href" : "https://api.bookshare.org/v2/titles/1041744/{format}"
}, {
"rel" : "coverimage",
"href" : "http://covers.bookshare.org/4538345.jpg"
}, {
"rel" : "thumbnail",
"href" : "http://covers.bookshare.org/4538345.jpg"
} ]
} ],
"authorFacets" : [ {
"value" : "Mark Twain",
"count" : 1
} ],
"categoryFacets" : [ {
"value" : "Literature and Fiction",
"count" : 12
} ],
"message" : null,
"links" : [ {
"rel" : "self",
"href" : "https://api.bookshare.org/v2/titles?country=CA&limit=1&title=Tom Sawyer&author=Mark Twain&isbn=9781551998121&categories=Literature and Fiction&sortOrder=dateAdded&direction=desc&api_key=abcdefg"
}, {
"rel" : "next",
"href" : "https://api.bookshare.org/v2/titles?country=CA&limit=1&title=Tom Sawyer&author=Mark Twain&isbn=9781551998121&categories=Literature and Fiction&sortOrder=dateAdded&direction=desc&api_key=abcdefg&start=abcde"
} ]
}Example Curl request
$ curl 'https://api.bookshare.org/v2/titles?country=CA&limit=1&title=Tom+Sawyer&author=Mark+Twain&isbn=9781551998121&categories=Literature+and+Fiction&categories=Children%27s+Books&sortOrder=dateAdded&direction=desc&api_key=abcdefg' -i -X GET2.12. User Account
A user account represents a specific user who is known about by the Bookshare system. Users may have various roles and other characteristics, which define the scope of possible features they have access to. In general, a user will need to a have an active subscription to access titles, and in most cases will also need a proof of disability.
Users can update certain information about themselves, while Membership Assistants or administrators will have access to see and modify the information about a larger collection of users; these are the endpoints that start with '/v2/accounts'. On those endpoints, a Membership Assistant is allowed to see and manage only those user accounts that are associated with their site, while administrators are allowed access to users across all sites.
2.12.1. Create my user account
POST /v2/myAccount
Description
Create a new user account, with the properties provided. Only available to anonymous users on certain API clients.
Parameters
Form Parameters
| Name | Description | Required | Schema | Default |
|---|---|---|---|---|
firstName |
The user’s first name. |
X |
String |
null |
lastName |
The user’s last name. |
X |
String |
null |
phoneNumber |
The user’s phone number. |
- |
String |
null |
emailAddress |
The user’s email address. This value will also be used as the username. |
X |
String |
null |
address1 |
The user’s street address of residence. |
- |
String |
null |
address2 |
Any extra street address information for the user. |
- |
String |
null |
city |
The user’s city of residence. |
- |
String |
null |
state |
The user’s state or province of residence. The value should be either a two-character postal abbreviation or an ISO 3166-2 subdivision code for the user’s country. This field is only relevant for subdivisions of the US and Canada. |
- |
String |
null |
country |
The user’s country of residence. The values should be a two-character ISO 3166 alpha-2 country code. |
X |
String |
null |
postalCode |
The user’s postal code of residence. |
- |
String |
null |
guardianFirstName |
The user’s guardian’s first name. Required if user is a minor, ignored otherwise. |
- |
String |
null |
guardianLastName |
The user’s guardian’s last name. Required if user is a minor, ignored otherwise. |
- |
String |
null |
guardianEmailAddress |
The user’s guardian’s email address. Required if user is a minor, ignored otherwise. |
- |
String |
null |
dateOfBirth |
The user’s date of birth. The value should be formatted as 'YYYY-MM-DD'. |
X |
String |
null |
language |
The user’s preferred language. The value should be a three-character ISO 639-2 alpha-3 language code |
- |
String |
null |
allowAdultContent |
True if the user should be allowed to find and download titles marked with adult content. This defaults to false for members who are minors. |
- |
Boolean |
null |
agreementSigned |
True if the user has signed the membership agreement. |
X |
Boolean |
null |
password |
The user’s password. It must be from 8-32 characters long, and contain at least one letter and one number. Required if googleIdToken is not provided. |
- |
String |
null |
googleIdToken |
An ID token representing the user’s Google account. Only available to select clients. Required if password is not provided. |
- |
String |
null |
Responses
| HTTP Code | Message | Datatype |
|---|---|---|
201 |
User Account summary response |
|
0 |
Unexpected error |
Example HTTP request
POST /v2/myAccount HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: api.bookshare.org
Content-Length: 243
firstName=Sally&lastName=Smith&country=US&emailAddress=sally%40smith.org&dateOfBirth=2015-01-02&guardianFirstName=Guardian&guardianLastName=Smith&guardianEmailAddress=guardian%40smith.org&password=testpass1&agreementSigned=true&api_key=abcdefgExample HTTP response
HTTP/1.1 201 Created
Location: https://api.bookshare.org/v2/myAccount
Content-Type: application/json
Content-Length: 889
{
"allows" : [ "PUT" ],
"name" : {
"firstName" : "Sally",
"lastName" : "Smith",
"middle" : null,
"prefix" : null,
"suffix" : null,
"links" : [ ]
},
"address" : {
"address1" : "",
"address2" : null,
"city" : "",
"state" : "",
"country" : "US",
"postalCode" : ""
},
"guardian" : {
"firstName" : "Guardian",
"lastName" : "Smith",
"middle" : null,
"prefix" : null,
"suffix" : null,
"links" : [ ]
},
"username" : "sally@smith.org",
"emailAddress" : "sally@smith.org",
"dateOfBirth" : "2015-01-02",
"phoneNumber" : null,
"studentStatus" : null,
"proofOfDisabilityStatus" : "missing",
"subscriptionStatus" : "missing",
"hasAgreement" : true,
"canDownload" : false,
"hasBooksharePlus" : false,
"links" : [ {
"rel" : "self",
"href" : "https://api.bookshare.org/v2/myAccount"
} ]
}Example Curl request
$ curl 'https://api.bookshare.org/v2/myAccount' -i -X POST \
-d 'firstName=Sally&lastName=Smith&country=US&emailAddress=sally%40smith.org&dateOfBirth=2015-01-02&guardianFirstName=Guardian&guardianLastName=Smith&guardianEmailAddress=guardian%40smith.org&password=testpass1&agreementSigned=true&api_key=abcdefg'2.12.2. Record UTM data
POST /v2/utm
Description
Record a marketing campaign referral. Only available to certain API clients.
Parameters
Form Parameters
| Name | Description | Required | Schema | Default |
|---|---|---|---|---|
campaign |
The name of the campaign. |
X |
String |
null |
source |
The referrer. Must be fewer than 32 characters. |
- |
String |
null |
medium |
The marketing medium. Must be fewer than 32 characters. |
- |
String |
null |
term |
The paid keyword. Must be fewer than 32 characters. |
- |
String |
null |
content |
Used to differentiate creatives. Must be fewer than 32 characters. |
- |
String |
null |
Example HTTP request
POST /v2/utm HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: api.bookshare.org
Content-Length: 74
campaign=summer-campaign&source=summer-mailer&medium=email&api_key=abcdefgExample HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 78
{
"key" : "SUCCESS",
"messages" : [ "UTM data submitted successfully." ]
}Example Curl request
$ curl 'https://api.bookshare.org/v2/utm' -i -X POST \
-d 'campaign=summer-campaign&source=summer-mailer&medium=email&api_key=abcdefg'2.12.3. Get my recommendation profile
GET /v2/myAccount/recommendationProfile
Description
Get property choices that guide title recommendations for the authenticated user.
Responses
| HTTP Code | Message | Datatype |
|---|---|---|
200 |
Recommendation Profile |
|
0 |
Unexpected error |
Example HTTP request
GET /v2/myAccount/recommendationProfile?api_key=abcdefg HTTP/1.1
Host: api.bookshare.orgExample HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 590
{
"allows" : [ "PUT" ],
"includeGlobalCollection" : false,
"includedAuthors" : [ "Mark Twain" ],
"excludedAuthors" : [ ],
"includedContentWarnings" : null,
"excludedContentWarnings" : [ ],
"includedCategories" : [ {
"name" : "Humor",
"description" : "Humor",
"categoryType" : "Bookshare",
"code" : null,
"links" : [ ]
} ],
"excludedCategories" : [ ],
"narratorGender" : "female",
"narratorType" : "human",
"readingAge" : null,
"links" : [ {
"rel" : "self",
"href" : "https://api.bookshare.org/v2/myAccount/recommendationProfile"
} ]
}Example Curl request
$ curl 'https://api.bookshare.org/v2/myAccount/recommendationProfile?api_key=abcdefg' -i -X GET2.12.4. Get my account downloads
GET /v2/myAccount/history
Description
Request a download history list of the authenticated user making the request.
Parameters
Query Parameters
| Name | Description | Required | Schema | Default |
|---|---|---|---|---|
limit |
Maximum number of results to include. The maximum allowed is 100 |
- |
Integer |
10 |
sortOrder |
Primary sorting field. |
- |
enum [title, author, dateDownloaded] |
[dateDownloaded] |
direction |
Direction for sorting. |
- |
enum [asc, desc] |
[desc] |
start |
If null or empty, it means to start at the beginning of the result set. Otherwise, it should be the value of 'next' that was returned from the previous request. |
- |
String |
null |
Responses
| HTTP Code | Message | Datatype |
|---|---|---|
200 |
Title Download List response |
|
0 |
Unexpected error |
Example HTTP request
GET /v2/myAccount/history?sortOrder=dateDownloaded&direction=asc&limit=2&api_key=abcdefg HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: api.bookshare.orgExample HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 1377
{
"limit" : 2,
"next" : null,
"totalResults" : 1,
"allows" : null,
"titleDownloads" : [ {
"bookshareId" : 1041744,
"title" : "The Adventures of Tom Sawyer",
"authors" : [ {
"firstName" : "Mark",
"lastName" : "Twain",
"middle" : null,
"prefix" : null,
"suffix" : null,
"links" : [ ]
} ],
"format" : {
"formatId" : "DAISY",
"name" : "DAISY"
},
"status" : {
"key" : "DOWNLOADED",
"messages" : null
},
"packagingStatus" : {
"key" : "DOWNLOADED",
"messages" : null
},
"downloadStatus" : {
"key" : "",
"messages" : null
},
"downloadedFor" : null,
"downloadedBy" : "",
"dateDownloaded" : "2017-10-20T00:00:00Z",
"dateRequested" : "2017-10-19T00:00:00Z",
"links" : [ {
"rel" : "self",
"href" : "https://api.bookshare.org/v2/titles/12345"
}, {
"rel" : "download",
"href" : "https://api.bookshare.org/v2/titles/12345/{format}"
}, {
"rel" : "coverimage",
"href" : "http://covers.bookshare.org/4538345.jpg"
}, {
"rel" : "thumbnail",
"href" : "http://covers.bookshare.org/4538345.jpg"
} ]
} ],
"links" : [ {
"rel" : "self",
"href" : "https://api.bookshare.org/v2/myAccount/history?sortOrder=dateDownloaded&direction=asc&limit=2&api_key=abcdefg"
} ]
}Example Curl request
$ curl 'https://api.bookshare.org/v2/myAccount/history?sortOrder=dateDownloaded&direction=asc&limit=2&api_key=abcdefg' -i -X GET \
-H 'Content-Type: application/x-www-form-urlencoded'2.12.5. Get my account preferences
GET /v2/myAccount/preferences
Description
Request the set of account preferences associated with the authenticated user.
Responses
| HTTP Code | Message | Datatype |
|---|---|---|
200 |
User Account preferences response |
|
0 |
Unexpected error |
Example HTTP request
GET /v2/myAccount/preferences?api_key=abcdefg HTTP/1.1
Host: api.bookshare.orgExample HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 431
{
"allows" : [ "PUT" ],
"allowAdultContent" : false,
"showAllBooks" : false,
"showRecommendations" : true,
"language" : "eng",
"format" : {
"formatId" : "DAISY",
"name" : "DAISY"
},
"brailleGrade" : "contracted",
"useUeb" : true,
"brailleFormat" : "refreshable",
"brailleCellLineWidth" : 40,
"links" : [ {
"rel" : "self",
"href" : "https://api.bookshare.org/v2/myAccount/preferences"
} ]
}Example Curl request
$ curl 'https://api.bookshare.org/v2/myAccount/preferences?api_key=abcdefg' -i -X GET2.12.6. Get my account summary
GET /v2/myAccount
Description
Request an account summary of the authenticated user making the request. If a user is a sponsor, a link leading to their organization’s members will be returned in the 'links' section as well.
Responses
| HTTP Code | Message | Datatype |
|---|---|---|
200 |
User Account summary response |
|
0 |
Unexpected error |
Example HTTP request
GET /v2/myAccount?api_key=abcdefg HTTP/1.1
Host: api.bookshare.orgExample HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 789
{
"allows" : [ "PUT" ],
"name" : {
"firstName" : "Sally",
"lastName" : "Smith",
"middle" : null,
"prefix" : null,
"suffix" : null,
"links" : [ ]
},
"address" : {
"address1" : "123 Main Street",
"address2" : null,
"city" : "Smalltown",
"state" : "MN",
"country" : "US",
"postalCode" : "54321"
},
"guardian" : null,
"username" : "sally@smith.org",
"emailAddress" : "sally@smith.org",
"dateOfBirth" : "1990-01-02",
"phoneNumber" : "123-456-7890",
"studentStatus" : null,
"proofOfDisabilityStatus" : "active",
"subscriptionStatus" : "active",
"hasAgreement" : true,
"canDownload" : true,
"hasBooksharePlus" : false,
"links" : [ {
"rel" : "self",
"href" : "https://api.bookshare.org/v2/myAccount"
} ]
}Example Curl request
$ curl 'https://api.bookshare.org/v2/myAccount?api_key=abcdefg' -i -X GET2.12.7. Check whether a user name exists.
GET /v2/userNames/{userName}
Description
Return the given user name if it exists. Return an error if the user name is not in the system. Only available to anonymous users on certain API clients.
Parameters
Path Parameters
| Name | Description | Required | Schema | Default |
|---|---|---|---|---|
userName |
The username to search for. |
X |
String |
null |
Example HTTP request
GET /v2/userNames/sally@smith.org?api_key=abcdefg HTTP/1.1
Host: api.bookshare.orgExample HTTP response
HTTP/1.1 200 OK
Content-Disposition: inline;filename=f.txt
Content-Type: application/json
Content-Length: 36
{
"userName" : "sally@smith.org"
}Example Curl request
$ curl 'https://api.bookshare.org/v2/userNames/sally@smith.org?api_key=abcdefg' -i -X GET2.12.8. Create a Google access token
POST /v2/googleAccessToken
Description
Create a Google access token for use with Google APIs. Only available to certain API clients.
Parameters
Form Parameters
| Name | Description | Required | Schema | Default |
|---|---|---|---|---|
code |
Authorization code received from authorization request to Google. Required if the user has never authorized access before. |
- |
String |
null |
Responses
| HTTP Code | Message | Datatype |
|---|---|---|
200 |
Google Access Token response |
|
0 |
Unexpected error |
Example HTTP request
POST /v2/googleAccessToken HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: api.bookshare.org
Content-Length: 38
code=authorizationCode&api_key=abcdefgExample HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 102
{
"allows" : null,
"googleId" : "googleUserId",
"accessToken" : "accessToken",
"links" : [ ]
}Example Curl request
$ curl 'https://api.bookshare.org/v2/googleAccessToken' -i -X POST \
-d 'code=authorizationCode&api_key=abcdefg'2.12.9. Get user identity
GET /v2/me
Description
Request basic information about the authenticated user making the request.
Responses
| HTTP Code | Message | Datatype |
|---|---|---|
200 |
User identity response |
|
0 |
Unexpected error |
Example HTTP request
GET /v2/me?api_key=abcdefg HTTP/1.1
Host: api.bookshare.orgExample HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 203
{
"username" : "john@smith.com",
"links" : [ ],
"name" : {
"firstName" : "John",
"lastName" : "Smith",
"middle" : null,
"prefix" : null,
"suffix" : null,
"links" : [ ]
}
}Example Curl request
$ curl 'https://api.bookshare.org/v2/me?api_key=abcdefg' -i -X GET2.12.10. Update my recommendation profile
PUT /v2/myAccount/recommendationProfile
Description
Update property choices that guide title recommendations for the authenticated user.
Parameters
Form Parameters
| Name | Description | Required | Schema | Default |
|---|---|---|---|---|
includeGlobalCollection |
If true, the recommendation system should include titles from the Bookshare Global Collection. This defaults to false for members of private label sites. |
- |
Boolean |
false |
narratorType |
Limit results to those with audio artifacts that are voiced by the given narrator type. If format is not also specified, it will default to search for DAISY_AUDIO or DAISY_2_AUDIO. |
- |
enum [human, tts] |
null |
narratorGender |
Limit results to those with audio artifacts that are voiced by the given narrator type. If format is not also specified, it will default to search for DAISY_AUDIO or DAISY_2_AUDIO. |
- |
enum [female, male, otherNonBinary] |
null |
readingAge |
Limit results to those with a specific reading age. |
- |
Integer |
null |
excludedContentWarnings |
Limit recommendations to titles that do not match any of the given content warning flags. |
- |
enum [contentWarning, sex, violence, drugs, language, intolerance, adult, unrated] |
null |
includedContentWarnings |
Deprecated - Limit recommendations to titles that match at least one of the given content warning flags. |
- |
enum [contentWarning, sex, violence, drugs, language, intolerance, adult, unrated] |
null |
excludedCategories |
Limit recommendations to titles that do not match any of the given Bookshare categories. |
- |
String |
null |
includedCategories |
Limit recommendations to titles that match at least one of these Bookshare categories. |
- |
String |
null |
excludedAuthors |
Limit recommendations to titles that do not match any of the given authors. |
- |
String |
null |
includedAuthors |
Limit recommendations to titles that match at least one of these authors. |
- |
String |
null |
Responses
| HTTP Code | Message | Datatype |
|---|---|---|
200 |
Recommendation Profile |
|
0 |
Unexpected error |
Example HTTP request
PUT /v2/myAccount/recommendationProfile HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: api.bookshare.org
Content-Length: 248
includeGlobalCollection=true&includedAuthors=Isaac+Asimov&includedAuthors=Arthur+Clarke&excludedAuthors=Orson+Scott+Card&excludedContentWarnings=intolerance&excludedCategories=Humor&narratorGender=male&narratorType=tts&readingAge=12&api_key=abcdefgExample HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 635
{
"allows" : [ "PUT" ],
"includeGlobalCollection" : true,
"includedAuthors" : [ "Isaac Asimov", "Arthur Clarke" ],
"excludedAuthors" : [ "Orson Scott Card" ],
"includedContentWarnings" : null,
"excludedContentWarnings" : [ "intolerance" ],
"includedCategories" : [ ],
"excludedCategories" : [ {
"name" : "Humor",
"description" : "Humor",
"categoryType" : "Bookshare",
"code" : null,
"links" : [ ]
} ],
"narratorGender" : "male",
"narratorType" : "tts",
"readingAge" : 12,
"links" : [ {
"rel" : "self",
"href" : "https://api.bookshare.org/v2/myAccount/recommendationProfile"
} ]
}Example Curl request
$ curl 'https://api.bookshare.org/v2/myAccount/recommendationProfile' -i -X PUT \
-d 'includeGlobalCollection=true&includedAuthors=Isaac+Asimov&includedAuthors=Arthur+Clarke&excludedAuthors=Orson+Scott+Card&excludedContentWarnings=intolerance&excludedCategories=Humor&narratorGender=male&narratorType=tts&readingAge=12&api_key=abcdefg'2.12.11. Update my account preferences
PUT /v2/myAccount/preferences
Description
Update the preference settings for the authenticated user.
Parameters
Form Parameters
| Name | Description | Required | Schema | Default |
|---|---|---|---|---|
allowAdultContent |
True if the user is allowed to find and download titles marked with adult content. This defaults to false for members who are minors. |
- |
Boolean |
null |
showAllBooks |
True if books marked as low quality should be included in search results. The default is false. |
- |
Boolean |
false |
showRecommendations |
True if the user would like to opt-in to receiving personalized recommendations. The default is true. |
- |
Boolean |
true |
language |
Language preference of the user. The value should be a three-character ISO 639-2 alpha-3 language code. |
- |
String |
null |
format |
Preferred format when downloading a title. Can be used by clients to suggest a title’s format when that format is available. |
- |
enum [DAISY, DAISY_AUDIO, DAISY_2_AUDIO, BRF, EPUB3, PDF, DOCX] |
null |
brailleGrade |
The preferred Braille grade (uncontracted or contracted) when downloading generated BRF. |
- |
enum [uncontracted, contracted] |
null |
brailleFormat |
The format of the Braille (refreshable or embossable) that will be created when downloading generated BRF. An updated Braille format must be submitted with an updated compatible Braille cell line width in order to be accepted. |
- |
enum [refreshable, embossable] |
null |
brailleCellLineWidth |
The maximum number of cells to create per line when generating BRF. For refreshable Braille, the allowed values are 18, 20, 32, 40, 70, or 80. For embossable Braille, the allowed values are 28 and 40. An updated Braille cell line width must be submitted with an updated compatible Braille format in order to be accepted. |
- |
Integer |
null |
useUeb |
True if English-language books should use UEB, rather than EBAE when downloading generated BRF. The default is false. |
- |
Boolean |
false |
Responses
| HTTP Code | Message | Datatype |
|---|---|---|
200 |
User Account preferences response |
|
0 |
Unexpected error |
Example HTTP request
PUT /v2/myAccount/preferences HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: api.bookshare.org
Content-Length: 189
brailleGrade=grade_2&brailleFormat=refreshable&useUeb=true&brailleCellLineWidth=40&allowAdultContent=true&showAllBooks=true&format=BRF&language=spa&showRecommendations=false&api_key=abcdefgExample HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 426
{
"allows" : [ "PUT" ],
"allowAdultContent" : true,
"showAllBooks" : true,
"showRecommendations" : false,
"language" : "spa",
"format" : {
"formatId" : "BRF",
"name" : "BRF"
},
"brailleGrade" : "contracted",
"useUeb" : true,
"brailleFormat" : "refreshable",
"brailleCellLineWidth" : 40,
"links" : [ {
"rel" : "self",
"href" : "https://api.bookshare.org/v2/myAccount/preferences"
} ]
}Example Curl request
$ curl 'https://api.bookshare.org/v2/myAccount/preferences' -i -X PUT \
-d 'brailleGrade=grade_2&brailleFormat=refreshable&useUeb=true&brailleCellLineWidth=40&allowAdultContent=true&showAllBooks=true&format=BRF&language=spa&showRecommendations=false&api_key=abcdefg'3. Models
3.1. Accessibility Certification
| Field Name | Description | Type | Format | Nullable |
|---|---|---|---|---|
certifiedBy |
Identifies a party responsible for the testing and certification of the accessibility of this artifact |
String |
||
certifierCredential |
Identifies a credential or badge that establishes the authority of the party identified in the associated certifiedBy property to certify content accessible |
String |
||
certifierReport |
Provides a link to an accessibility report created by the party identified |
String |
3.2. Accessibility Feature
| Field Name | Description | Type | Format | Nullable |
|---|---|---|---|---|
accessibilityFeature |
Identifies the type of accessibility feature with values coming from ONIX codelist 196 and W3C Discoverability Vocab |
String |
||
description |
Additional information about the feature |
String |
3.3. Accessibility Metadata
| Field Name | Description | Type | Format | Nullable |
|---|---|---|---|---|
accessibilitySummary |
A human readable field summarizing the accessibility metadata |
String |
||
accessibilityConformances |
Set of specifications this artifact conforms to (EPUB specification levels, WCAG versions, and WCAG levels). For more information see the W3C EPUB Accessibility and ONIX Codelist 196 |
List of String |
||
accessibilityCertifications |
The person or organization that certified the accessibility of this artifact |
List of Accessibility Certification |
||
accessibilityFeatures |
The accessibility features that apply to this artifact |
List of Accessibility Feature |
||
accessibilityHazards |
Set of accessibility hazards that apply to this artifact with values coming from W3C Discoverability Vocab |
List of String |
||
accessModes |
The ways in which information is encoded in this artifact with values from W3C Discoverability Vocab |
List of String |
||
accessModesSufficient |
A list of single or combined accessModes that are sufficient to understand all the intellectual content of this artifact with values from W3C Discoverability Vocab |
List of String |
3.4. Address
| Field Name | Description | Type | Format | Nullable |
|---|---|---|---|---|
address1 |
The primary street address. |
String |
||
address2 |
Extra street address information, if any. |
String |
||
city |
A city name. |
String |
||
state |
The state or province or other subdivision of the country. The value will be an ISO-3166-2 subdivision code for the associated country. |
String |
||
country |
The country code. The value will be an ISO 3166 alpha-2 country code. |
String |
||
postalCode |
The postal code, if any, for the given address. |
String |
3.5. Alert
| Field Name | Description | Type | Format | Nullable |
|---|---|---|---|---|
id |
Alert identifier code. See the list of alert codes for the set of possible values. |
String |
||
message |
Message string that describes the alert situation. |
String |
||
type |
Alert type. |
String |
enum [info, warn, error] |
3.6. Artifact Metadata
| Field Name | Description | Type | Format | Nullable |
|---|---|---|---|---|
format |
The format identifier of the artifact this information relates to |
String |
||
globalBookServiceId |
An identifier from a global book service such as ABC |
String |
||
producer |
The person or organization that produced this particular artifact |
String |
||
supplier |
The person or organization who provided this artifact to be included in the collection |
String |
||
narrator |
||||
brailleGrade |
Braille grade, contracted or uncontracted |
String |
enum [contracted, uncontracted] |
X |
brailleCode |
Braille code, such as UEB or EBAE |
String |
||
brailleType |
Braille type, automated or transcribed |
String |
enum [automated, transcribed] |
X |
brailleMusicScoreLayout |
Braille music score layout, barOverBar or barByBar |
String |
enum [barOverBar, barByBar] |
X |
duration |
The length of the audio artifact, in ISO 8601 duration format (PTnHnMnS) |
String |
||
fundingSource |
The person or organization who funded the production of this artifact |
String |
||
numberOfVolumes |
The number of Braille volumes contained in this artifact |
Integer |
||
externalIdentifierCode |
The external identifier for this artifact, assigned by the site responsible for this artifact |
String |
||
transcriber |
||||
accessibilityMetadata |
||||
dateAdded |
Date that the artifact was originally added to the collection |
Date |
date-time |
3.7. Assigned Title Metadata Summary
| Field Name | Description | Type | Format | Nullable |
|---|---|---|---|---|
bookshareId |
Unique identifier of the title |
String |
||
title |
Title of the book or reading material |
String |
||
subtitle |
Subtitle of the book or reading material |
String |
||
authors |
Deprecated - Author names of the title |
List of Name |
||
seriesTitle |
Title of the series to which the book belongs, if applicable |
String |
||
seriesNumber |
Number of the book within the series to which it belongs |
String |
||
isbn13 |
ISBN of the book or reading material |
String |
||
available |
True if the current user is allowed to download the title |
Boolean |
||
publishDate |
The date this title was added to the collection |
Date |
date-time |
|
copyrightDate |
The copyright year of this title |
String |
year |
|
synopsis |
Synopsis of the title |
String |
||
languages |
Languages of the title. The value will be a three-character ISO 639-2 alpha-3 language code |
List of String |
||
formats |
Formats in which the title is available |
List of Format |
||
titleContentType |
General type of content found in this title. Most titles will be text, but specialized titles could be primarily content like music scores or graphic images. |
String |
||
nimac |
True if this title came from the NIMAC, which has special meaning to US school members. |
Boolean |
||
numImages |
Number of images in this title |
Integer |
||
composers |
Deprecated - Composer names of the sheet music |
List of Name |
||
instruments |
Instruments of the sheet music |
String |
||
vocalParts |
Vocal parts of the sheet music |
String |
||
owner |
The owner of the document |
String |
||
assignedBy |
The name of the sponsor who assigned the title |
String |
||
dateAdded |
Date assigned to the member |
String |
||
dateDownloaded |
The last date the member accessed the book |
String |
||
links |
List of Link |
|||
allows |
Operations allowed: PUT, for Collection Assistants |
List of String |
enum [PUT] |
3.8. List of Assigned Title Metadata Summaries
| Field Name | Description | Type | Format | Nullable |
|---|---|---|---|---|
message |
||||
totalResults |
The number of results found that match the search criteria |
Integer |
||
next |
Token that can be used as the 'start' value to retrieve another group of results |
String |
||
limit |
Maximum number of results included in this set |
Integer |
||
titles |
List of Assigned Title Metadata Summary |
|||
allows |
Operations allowed: None |
List of String |
||
links |
List of Link |
3.9. BISAC Code
| Field Name | Description | Type | Format | Nullable |
|---|---|---|---|---|
code |
The BISAC code. |
String |
||
description |
The BISAC code description. |
String |
3.10. List of BISAC Codes
| Field Name | Description | Type | Format | Nullable |
|---|---|---|---|---|
totalResults |
The number of results found that match the search criteria |
Integer |
||
next |
Token that can be used as the 'start' value to retrieve another group of results |
String |
||
limit |
Maximum number of results included in this set |
Integer |
||
bisacCodes |
List of BISAC Code |
3.11. Bookmark
| Field Name | Description | Type | Format | Nullable |
|---|---|---|---|---|
bookshareId |
Unique identifier of the title. |
String |
||
format |
||||
location |
The format-specific location identifier to signify the bookmark’s location. For example, the EPUB3 format may use EPUB Canonical Fragment Identifiers. |
String |
||
text |
The text at the location of the bookmark. |
String |
||
position |
The index of the current section where the bookmark resides within the publication spine. |
Integer |
||
progression |
The percent progress within the current section at the location of the bookmark. |
Double |
double |
|
totalProgression |
The percent progress within the whole title at the location of the bookmark. |
Double |
double |
|
dateCreated |
The date when the bookmark was added. |
Date |
date-time |
|
links |
List of Link |
|||
allows |
Operations allowed: DELETE |
List of String |
enum [DELETE] |
3.12. List of My Bookmarks
| Field Name | Description | Type | Format | Nullable |
|---|---|---|---|---|
totalResults |
The number of results found that match the search criteria |
Integer |
||
next |
Token that can be used as the 'start' value to retrieve another group of results |
String |
||
limit |
Maximum number of results included in this set |
Integer |
||
bookmarks |
List of Bookmark |
|||
allows |
Operations allowed: POST = create a new bookmark |
List of String |
enum [POST] |
|
links |
List of Link |
3.13. List of Categories
| Field Name | Description | Type | Format | Nullable |
|---|---|---|---|---|
totalResults |
The number of results found that match the search criteria |
Integer |
||
next |
Token that can be used as the 'start' value to retrieve another group of results |
String |
||
limit |
Maximum number of results included in this set |
Integer |
||
categories |
List of Category Summary |
|||
links |
List of Link |
3.14. Category
| Field Name | Description | Type | Format | Nullable |
|---|---|---|---|---|
name |
Identifier of the subject category |
String |
||
description |
Descriptive name of the subject category, localized when possible to the user’s locale. |
String |
||
categoryType |
Category type, Bookshare or BISAC |
String |
enum [Bookshare, BISAC] |
|
code |
Code that represents the category, may be null. |
String |
||
links |
List of Link |
3.15. Category Summary
| Field Name | Description | Type | Format | Nullable |
|---|---|---|---|---|
name |
Descriptive name of the subject category. |
String |
||
description |
Descriptive name of the subject category, localized when possible to the user’s locale. |
String |
||
titleCount |
Number of titles that are associated with this category. |
Integer |
||
links |
List of Link |
3.16. Content Warning Values
| Enum Values |
|---|
contentWarning |
sex |
violence |
drugs |
language |
intolerance |
adult |
unrated |
3.17. Contributor
| Field Name | Description | Type | Format | Nullable |
|---|---|---|---|---|
name |
||||
type |
Type of contributor to a title or artifact. |
String |
enum [author, coWriter, epilogueBy, forwardBy, introductionBy, editor, composer, arranger, lyricist, translator, transcriber, abridger, adapter] |
|
links |
List of Link |
3.18. Contributor Name
| Field Name | Description | Type | Format | Nullable |
|---|---|---|---|---|
displayName |
Name as a full combination of all parts, first name before last name. |
String |
||
indexName |
Name as it would be indexed for sorting. |
String |
||
links |
List of Link |
3.19. Error
| Field Name | Description | Type | Format | Nullable |
|---|---|---|---|---|
key |
String |
|||
messages |
List of String |
3.20. Facet
| Field Name | Description | Type | Format | Nullable |
|---|---|---|---|---|
value |
The search facet value that can be used to further filter subsequent searches. |
String |
||
count |
The number of times the value is represented in the search results. |
Integer |
3.21. Format
| Field Name | Description | Type | Format | Nullable |
|---|---|---|---|---|
formatId |
Unique identifier of the format. |
String |
||
name |
Descriptive name of the format, suitable for display. |
String |
3.22. Google Token
| Field Name | Description | Type | Format | Nullable |
|---|---|---|---|---|
google_id |
Google user id |
String |
||
access_token |
An access token for use with Google’s APIs |
String |
3.23. Grade
| Field Name | Description | Type | Format | Nullable |
|---|---|---|---|---|
name |
Descriptive name of the grade category |
String |
||
gradeId |
Deprecated - Unique identifier |
String |
||
gradeCode |
Code value of the grade. Values are from ONIX codelist 77 for US grades, BIC for UK grades |
String |
||
links |
List of Link |
3.24. Highlight
| Field Name | Description | Type | Format | Nullable |
|---|---|---|---|---|
bookshareId |
Unique identifier of the title. |
String |
||
format |
||||
startLocation |
The format-specific location identifier to signify the highlight’s start location. For example, the EPUB3 format may use EPUB Canonical Fragment Identifiers. |
String |
||
endLocation |
The format-specific end location identifier to signify the highlight’s end location. For example, the EPUB3 format may use EPUB Canonical Fragment Identifiers. |
String |
||
highlightText |
The text at the location of the highlight. |
String |
||
annotationNote |
A string that a user can attach to a highlight. |
String |
||
color |
The hexadecimal color code of the highlight. |
String |
||
startPosition |
The start index of the current section where the highlight resides within the publication spine. |
Integer |
||
startProgression |
The percent progress within the current section at the start location of the highlight. |
Double |
double |
|
startTotalProgression |
The percent progress within the whole title at the start location of the highlight. |
Double |
double |
|
endPosition |
The end index of the current section where the highlight resides within the publication spine. |
Integer |
||
endProgression |
The percent progress within the current section at the end location of the highlight. |
Double |
double |
|
endTotalProgression |
The percent progress within the whole title at the end location of the highlight. |
Double |
double |
|
dateUpdated |
The date when the highlight was last updated. |
Date |
date-time |
|
allows |
Operations allowed: PUT = update a highlight, DELETE = delete a highlight. |
List of String |
enum [PUT, DELETE] |
|
links |
List of Link |
3.25. List of My Highlights
| Field Name | Description | Type | Format | Nullable |
|---|---|---|---|---|
next |
Token that can be used as the 'start' value to retrieve another group of results. |
String |
||
limit |
Maximum number of results included in this set. |
Integer |
||
highlights |
List of Highlight |
|||
allows |
Operations allowed: POST = create a new highlight. |
List of String |
enum [POST] |
|
links |
List of Link |
3.26. Link
| Field Name | Description | Type | Format | Nullable |
|---|---|---|---|---|
rel |
A relationship name |
String |
||
href |
An absolute or relative URI for a resource request |
String |
3.27. Organization Member Summary
| Field Name | Description | Type | Format | Nullable |
|---|---|---|---|---|
userAccountId |
Unique identifier of the user account. |
String |
||
userName |
User name of the user account, hidden if sponsors are not allowed to manage this user’s account. |
String |
||
name |
||||
emailAddress |
The member’s email address, hidden if sponsors are not allowed to manage this user’s account. |
String |
||
allowAdultContent |
True if the member is allowed to find and download titles marked with adult content. |
Boolean |
||
phoneNumber |
The member’s preferred phone number. |
String |
||
language |
Language preference of the member. The value will be a three-character ISO 639-2 alpha-3 language code. |
String |
||
roles |
The roles assigned to the member. These define some of the boundaries on features available to the member. |
List of String |
||
hasAgreement |
True if current signed agreement is on file. |
Boolean |
||
locked |
True if the user account is locked. |
Boolean |
||
canDownload |
True if the member can download titles. |
Boolean |
||
dateOfBirth |
The member’s date of birth. The value will be formatted as 'YYYY-MM-DD'. |
String |
||
grade |
The member’s current grade. Values are from ONIX codelist 77 for US grades, BIC for UK grades. |
String |
||
preferredFormat |
||||
plans |
The disability plans for the user. |
List of String |
enum [iep, section504] |
|
disabilities |
The type of disability involved. |
List of String |
enum [visual, learning, physical, nonspecific] |
|
onQuickList |
True if the member is on the quicklist of the sponsor making the request. |
Boolean |
||
sponsorManageable |
True if the member’s account may be fully managed by sponsors in their organization. |
Boolean |
||
allows |
Operations allowed: PUT |
List of String |
enum [PUT] |
|
links |
List of Link |
3.28. List of Member Summaries
| Field Name | Description | Type | Format | Nullable |
|---|---|---|---|---|
totalResults |
The number of results found that match the search criteria |
Integer |
||
next |
Token that can be used as the 'start' value to retrieve another group of results |
String |
||
limit |
Maximum number of results included in this set |
Integer |
||
memberSummaries |
List of Organization Member Summary |
|||
links |
List of Link |
3.29. Organization Member Title Availability
| Field Name | Description | Type | Format | Nullable |
|---|---|---|---|---|
name |
||||
userAccountId |
Unique identifier of the user account. |
String |
||
userName |
User name of the user account, hidden if sponsors are not allowed to manage this user’s account. |
String |
||
emailAddress |
The user’s email address. |
String |
||
dateOfBirth |
The user’s date of birth. The value will be formatted as 'YYYY-MM-DD'. |
String |
||
grade |
The user’s current grade. Values are from ONIX codelist 77 for US grades, BIC for UK grades. |
String |
||
plans |
The disability plans for the user. |
List of String |
enum [iep, section504] |
|
disabilities |
The type of disability involved. |
List of String |
enum [visual, learning, physical, nonspecific] |
|
roles |
The roles assigned to the user. These define some of the boundaries on features available to the user. |
List of String |
||
onQuickList |
True if the user is on the quicklist of the sponsor making the request. |
Boolean |
||
titleAccessAlerts |
List of informational alerts if the requesting sponsor is not allowed to download the title for this user. See the list of title access alert codes for the set of possible values. |
List of Alert |
||
assigned |
True if the title is assigned to the user. |
Boolean |
||
preferredFormat |
||||
links |
List of Link |
|||
allows |
Operations allowed: None |
List of String |
3.30. List of Member Title Availabilities
| Field Name | Description | Type | Format | Nullable |
|---|---|---|---|---|
totalResults |
The number of results found that match the search criteria |
Integer |
||
next |
Token that can be used as the 'start' value to retrieve another group of results |
String |
||
limit |
Maximum number of results included in this set |
Integer |
||
memberTitleAvailabilities |
||||
links |
List of Link |
3.31. My Account Preferences
| Field Name | Description | Type | Format | Nullable |
|---|---|---|---|---|
allowAdultContent |
True if the user is allowed to find and download titles marked with adult content. This defaults to false for members who are minors. |
Boolean |
||
showAllBooks |
True if books marked as low quality should be included in search results. The default is false. |
Boolean |
||
showRecommendations |
True if the user would like to opt-in to receiving personalized recommendations. The default is true. |
Boolean |
||
language |
Language preference of the user. The value will be a three-character ISO 639-2 alpha-3 language code. |
String |
||
format |
||||
brailleGrade |
The preferred Braille grade (uncontracted or contracted) when downloading generated BRF. |
String |
enum [uncontracted, contracted] |
|
useUeb |
True if English-language books should use UEB, rather than EBAE when downloading generated BRF. The default is false. |
Boolean |
||
brailleFormat |
The format of the Braille (refreshable or embossable) that will be created when downloading generated BRF. |
String |
enum [refreshable, embossable] |
|
brailleCellLineWidth |
The maximum number of cells to create per line when generating BRF. For refreshable Braille, the allowed values are 18, 20, 32, 40, 70, or 80. For embossable Braille, the allowed values are 28 and 40. |
Integer |
||
links |
List of Link |
|||
allows |
Operations allowed: PUT |
List of String |
enum [PUT] |
3.32. My Account Summary
| Field Name | Description | Type | Format | Nullable |
|---|---|---|---|---|
name |
||||
username |
The user’s username to identify them to the system. |
String |
||
address |
||||
guardian |
||||
dateOfBirth |
The user’s date of birth. The value will be formatted as 'YYYY-MM-DD'. |
String |
||
phoneNumber |
The user’s preferred phone number. |
String |
||
proofOfDisabilityStatus |
Status of proof of disability. |
String |
enum [active, missing] |
|
subscriptionStatus |
Status of subscription. |
String |
enum [active, expired, missing] |
|
studentStatus |
||||
hasAgreement |
True if current signed agreement is on file. |
Boolean |
||
canDownload |
True if user account can download titles. |
Boolean |
||
hasBooksharePlus |
True if user account has access to Bookshare Plus features. |
Boolean |
||
links |
List of Link |
|||
allows |
Operations allowed: PUT |
List of String |
enum [PUT] |
3.33. My Organization Summary
| Field Name | Description | Type | Format | Nullable |
|---|---|---|---|---|
organizationName |
The name of the organization |
String |
||
address |
||||
phoneNumber |
The organization’s phone number. |
String |
||
webSite |
The organization’s website. |
String |
||
organizationType |
The type of organization. |
String |
||
primaryContact |
||||
links |
List of Link |
|||
allows |
Operations allowed: PUT |
List of String |
enum [PUT] |
3.34. Name
| Field Name | Description | Type | Format | Nullable |
|---|---|---|---|---|
firstName |
First name of the individual or entity |
String |
||
lastName |
Last name of the individual or entity |
String |
||
middle |
Middle name, or initial, if any |
String |
||
prefix |
Prefix, if any, such as Mr., Mrs., Dr. |
String |
||
suffix |
Suffix, if any, such as Jr., Sr., III |
String |
||
links |
List of Link |
3.35. Narrator
| Field Name | Description | Type | Format | Nullable |
|---|---|---|---|---|
name |
The narrator’s name |
String |
||
gender |
The narrator’s gender |
String |
enum [male, female, otherNonBinary] |
|
type |
The source of speech |
String |
enum [tts, human] |
3.36. Organization Type
Possible values at /v2/organizationTypes
| Field Name | Description | Type | Format | Nullable |
|---|---|---|---|---|
name |
Unique descriptive name of the organization type |
String |
||
description |
Description of the organization type |
String |
3.37. List of Organization Types
| Field Name | Description | Type | Format | Nullable |
|---|---|---|---|---|
organizationTypes |
List of organization types |
List of Organization Type |
||
links |
List of Link |
3.38. Periodical Edition
| Field Name | Description | Type | Format | Nullable |
|---|---|---|---|---|
editionId |
Unique identifier of a periodical edition |
String |
||
editionName |
Name of the edition |
String |
||
publicationDate |
Publication date of the edition |
Date |
date-time |
|
expirationDate |
Expiration date of the edition |
Date |
date-time |
|
formats |
Available formats |
List of Format |
||
links |
List of Link |
3.39. List of Periodical Editions
| Field Name | Description | Type | Format | Nullable |
|---|---|---|---|---|
message |
||||
totalResults |
The number of results found that match the search criteria |
Integer |
||
next |
Token that can be used as the 'start' value to retrieve another group of results |
String |
||
limit |
Maximum number of results included in this set |
Integer |
||
periodicalEditions |
List of Periodical Edition |
|||
allows |
Operations allowed: None |
List of String |
||
links |
List of Link |
3.40. Periodical Edition Summary
| Field Name | Description | Type | Format | Nullable |
|---|---|---|---|---|
editionId |
Unique identifier of the periodical edition |
String |
||
editionName |
Name of the edition |
String |
3.41. Periodical Series Metadata Summary
| Field Name | Description | Type | Format | Nullable |
|---|---|---|---|---|
seriesId |
Unique identifier of the periodical series |
String |
||
title |
Title of the periodical |
String |
||
issn |
ISSN of the periodical |
String |
||
description |
Description of the periodical |
String |
||
publisher |
Publisher of the periodical |
String |
||
seriesType |
Type of periodical |
String |
enum [newspaper, magazine, journal] |
|
externalCategoryCode |
External Category Code |
String |
||
categories |
Categories of the periodical |
List of Category |
||
languages |
Languages of the periodical. The value will be a three-character ISO 639-2 alpha-3 language code |
List of String |
||
countries |
Countries to which this periodical is restricted for distribution. The values should be a two-character ISO 3166 alpha-2 country code. |
List of String |
||
editionCount |
The number of editions available for this periodical |
Integer |
||
latestEdition |
||||
links |
List of Link |
3.42. List of Periodical Series Metadata Summaries
| Field Name | Description | Type | Format | Nullable |
|---|---|---|---|---|
message |
||||
totalResults |
The number of results found that match the search criteria |
Integer |
||
next |
Token that can be used as the 'start' value to retrieve another group of results |
String |
||
limit |
Maximum number of results included in this set |
Integer |
||
periodicals |
||||
allows |
Operations allowed: None |
List of String |
||
links |
List of Link |
3.43. Popular List
| Field Name | Description | Type | Format | Nullable |
|---|---|---|---|---|
id |
Unique identifier of the popular list. |
String |
||
description |
A description of what the popular list represents. |
String |
||
popularTitles |
List of Title Metadata Summary |
|||
totalResults |
The number of results found for most popular lists available |
Integer |
||
next |
Token that can be used as the 'start' value to retrieve another group of results |
String |
||
limit |
Maximum number of results included in this set |
Integer |
||
links |
List of Link |
3.44. List of Popular Lists
| Field Name | Description | Type | Format | Nullable |
|---|---|---|---|---|
totalResults |
The number of results found for most popular lists available |
Integer |
||
next |
Token that can be used as the 'start' value to retrieve another group of results |
String |
||
limit |
Maximum number of results included in this set |
Integer |
||
popularLists |
List of Popular List Summary |
|||
links |
List of Link |
3.45. Popular List Summary
| Field Name | Description | Type | Format | Nullable |
|---|---|---|---|---|
id |
Unique identifier of the popular list. |
String |
||
description |
A description of what the popular list represents. |
String |
||
links |
List of Link |
3.46. Reading List
| Field Name | Description | Type | Format | Nullable |
|---|---|---|---|---|
readingListId |
Unique identifier of the reading list |
String |
||
name |
Name given by the owner |
String |
||
description |
Description of the list given by the owner |
String |
||
owner |
Display name of the owner |
String |
||
titleCount |
Number of titles contained in this reading list |
Integer |
||
access |
Visibility of the list |
String |
enum [private, shared, org] |
|
memberCount |
Number of organization members assigned to this reading list |
Integer |
||
assignedBy |
If the current user is a member of the the list, the display name of the user who assigned them |
String |
||
subscriberCount |
Number of users subscribed in this reading list |
Integer |
||
dateUpdated |
Date that the reading list was last updated |
Date |
date-time |
|
allows |
Operations allowed: PUT = edit metadata |
List of String |
enum [PUT] |
|
links |
List of Link |
3.47. List of My Reading Lists
| Field Name | Description | Type | Format | Nullable |
|---|---|---|---|---|
totalResults |
The number of results found that match the search criteria |
Integer |
||
next |
Token that can be used as the 'start' value to retrieve another group of results |
String |
||
limit |
Maximum number of results included in this set |
Integer |
||
lists |
List of Reading List User View |
|||
allows |
Operations allowed: POST = create a new list |
List of String |
enum [POST] |
|
links |
List of Link |
3.48. Reading List Subscription
| Field Name | Description | Type | Format | Nullable |
|---|---|---|---|---|
enabled |
User is subscribed to this reading list |
Boolean |
||
allows |
Operations allowed: PUT = subscribe or unsubscribe |
List of String |
enum [PUT] |
|
links |
List of Link |
3.49. Reading List Title
| Field Name | Description | Type | Format | Nullable |
|---|---|---|---|---|
dateAdded |
The date this title was added to the reading list |
Date |
date-time |
|
bookshareId |
Unique identifier of the title |
String |
||
title |
Title of the book or reading material |
String |
||
subtitle |
Subtitle of the book or reading material |
String |
||
authors |
Deprecated - Author names of the title |
List of Name |
||
seriesTitle |
Title of the series to which the book belongs, if applicable |
String |
||
seriesNumber |
Number of the book within the series to which it belongs |
String |
||
isbn13 |
ISBN of the book or reading material |
String |
||
available |
True if the current user is allowed to download the title |
Boolean |
||
publishDate |
The date this title was added to the collection |
Date |
date-time |
|
copyrightDate |
The copyright year of this title |
String |
year |
|
synopsis |
Synopsis of the title |
String |
||
languages |
Languages of the title. The value will be a three-character ISO 639-2 alpha-3 language code |
List of String |
||
formats |
Formats in which the title is available |
List of Format |
||
titleContentType |
General type of content found in this title. Most titles will be text, but specialized titles could be primarily content like music scores or graphic images. |
String |
||
nimac |
True if this title came from the NIMAC, which has special meaning to US school members. |
Boolean |
||
numImages |
Number of images in this title |
Integer |
||
composers |
Deprecated - Composer names of the sheet music |
List of Name |
||
instruments |
Instruments of the sheet music |
String |
||
vocalParts |
Vocal parts of the sheet music |
String |
||
owner |
The owner of the document |
String |
||
ranking |
Ranking of the title within the collection |
Integer |
||
year |
The year that the title was included in the collection |
Integer |
||
month |
The month that the title was included in the collection |
Integer |
||
category |
The category of the title |
String |
||
award |
Award that the title has received |
String |
||
allows |
Operations allowed: DELETE = remove the title from the list |
List of String |
enum [DELETE] |
|
links |
List of Link |
3.50. List of Reading List Titles
| Field Name | Description | Type | Format | Nullable |
|---|---|---|---|---|
readingListId |
Unique identifier of the reading list |
String |
||
totalResults |
The number of results found that match the search criteria |
Integer |
||
next |
Token that can be used as the 'start' value to retrieve another group of results |
String |
||
limit |
Maximum number of results included in this set |
Integer |
||
titles |
List of Reading List Title |
|||
allows |
Operations allowed: POST = add a title to the list |
List of String |
enum [POST] |
|
links |
List of Link |
3.51. Reading List User View
| Field Name | Description | Type | Format | Nullable |
|---|---|---|---|---|
readingListId |
Unique identifier of the reading list |
String |
||
name |
Name given by the owner |
String |
||
description |
Description of the list given by the owner |
String |
||
owner |
Display name of the owner |
String |
||
titleCount |
Number of titles contained in this reading list |
Integer |
||
access |
Visibility of the list |
String |
enum [private, shared, org, public] |
|
memberCount |
Number of organization members assigned to this reading list |
Integer |
||
assignedBy |
If the current user is a member of the the list, the display name of the user who assigned them |
String |
||
subscription |
||||
dateUpdated |
Date that the reading list was last updated |
Date |
date-time |
|
allows |
Operations allowed: PUT = edit metadata |
List of String |
enum [PUT] |
|
links |
List of Link |
3.52. Reading Position
| Field Name | Description | Type | Format | Nullable |
|---|---|---|---|---|
bookshareId |
Unique identifier of the title. |
String |
||
format |
||||
location |
The last reported reading position location. Null if you have no recorded position for this book in this format. |
String |
||
dateAdded |
The date when the first reading activity event was added. Null if you have no recorded position for this book in this format. |
Date |
date-time |
|
dateModified |
The date when the latest reading activity event was added. Null if you have no recorded position for this book in this format. |
Date |
date-time |
|
links |
List of Link |
3.53. Recommendation Profile
| Field Name | Description | Type | Format | Nullable |
|---|---|---|---|---|
includeGlobalCollection |
True if the recommendation system should suggest titles from the Bookshare Global Collection. This defaults to false for members of private label sites. |
Boolean |
||
includedAuthors |
Limit results to titles that match at least one of the given authors. |
List of String |
||
excludedAuthors |
Limit results to titles that match none of the given authors. |
List of String |
||
includedCategories |
Limit results to titles that match at least one of the given Bookshare categories. |
List of Category |
||
excludedCategories |
Limit results to titles that match none of the given Bookshare categories. |
List of Category |
||
includedContentWarnings |
Deprecated - Limit results to titles that match at least one of the given content warnings. |
List of content_warning_values |
||
excludedContentWarnings |
Limit results to titles that match none of the given content warnings. |
List of content_warning_values |
||
narratorGender |
Limit results to the given narrator’s gender. |
String |
enum [male, female, otherNonBinary] |
X |
narratorType |
Limit results to the given source of speech. |
String |
enum [tts, human] |
X |
readingAge |
Limit results to titles that include the given reading age. |
Integer |
||
allows |
Operations allowed: PUT |
List of String |
enum [PUT] |
|
links |
List of Link |
3.54. Recommended Titles
| Field Name | Description | Type | Format | Nullable |
|---|---|---|---|---|
recommendedTitles |
List of Title Metadata Summary |
|||
totalResults |
The number of results for recommended titles. |
Integer |
||
next |
Token that can be used as the 'start' value to retrieve another group of results |
String |
||
limit |
Maximum number of results included in this set |
Integer |
||
links |
List of Link |
3.55. Reference Organization
| Field Name | Description | Type | Format | Nullable |
|---|---|---|---|---|
referenceOrgId |
Unique identifier of the reference organization. |
String |
||
name |
The name of the reference organization. |
String |
||
parentName |
The name of the reference organization’s parent reference organization, if present. |
String |
||
address |
||||
locationAddress |
3.56. List of Reference Organizations
| Field Name | Description | Type | Format | Nullable |
|---|---|---|---|---|
totalResults |
The number of results found that match the search criteria |
Integer |
||
next |
Token that can be used as the 'start' value to retrieve another group of results |
String |
||
limit |
Maximum number of results included in this set |
Integer |
||
referenceOrganizations |
List of Reference Organization |
|||
links |
List of Link |
3.57. Organization Sponsor Summary
| Field Name | Description | Type | Format | Nullable |
|---|---|---|---|---|
name |
||||
userAccountId |
Unique identifier of the user account |
String |
||
title |
The sponsor’s title. |
String |
||
emailAddress |
The sponsor’s email address. |
String |
||
phoneNumber |
The sponsor’s preferred phone number. |
String |
||
links |
List of Link |
|||
allows |
Operations allowed: PUT |
List of String |
enum [PUT] |
3.58. List of Sponsor Summaries
| Field Name | Description | Type | Format | Nullable |
|---|---|---|---|---|
totalResults |
The number of results found that match the search criteria |
Integer |
||
next |
Token that can be used as the 'start' value to retrieve another group of results |
String |
||
sponsorSummaries |
List of Organization Sponsor Summary |
|||
allows |
Operations allowed: None |
List of String |
||
links |
List of Link |
3.59. Status
| Field Name | Description | Type | Format | Nullable |
|---|---|---|---|---|
key |
String |
|||
messages |
List of String |
X |
3.60. Student status
| Field Name | Description | Type | Format | Nullable |
|---|---|---|---|---|
organizationName |
Name of the organization |
String |
||
grade |
3.61. Title Download
| Field Name | Description | Type | Format | Nullable |
|---|---|---|---|---|
title |
Title of the book or reading material |
String |
||
bookshareId |
Unique identifier of the title |
String |
||
authors |
Deprecated - Author names of the title |
List of Name |
||
format |
||||
status |
||||
packagingStatus |
||||
downloadStatus |
||||
dateDownloaded |
The date this title was downloaded |
Date |
date-time |
|
dateRequested |
The date that the title download was requested |
Date |
date-time |
|
downloadedFor |
Member name, if different than the requesting user |
String |
||
downloadedBy |
Sponsor name, if different than the requesting user |
String |
||
links |
List of Link |
3.62. List of Title Downloads
| Field Name | Description | Type | Format | Nullable |
|---|---|---|---|---|
totalResults |
The number of results found that match the criteria |
Integer |
||
next |
Token that can be used as the 'start' value to retrieve another group of results |
String |
||
titleDownloads |
List of Title Download |
|||
allows |
Operations allowed: None |
List of String |
||
links |
List of Link |
3.63. Title File Resource
| Field Name | Description | Type | Format | Nullable |
|---|---|---|---|---|
mimeType |
The MIME type of the title file resource |
String |
||
size |
The size of the title file resource in bytes |
String |
||
localURI |
A local name for the Reading System to use to reference the title file resource |
String |
||
lastModifiedDate |
Indicates when this specific title file resource was last updated |
Date |
date-time |
|
links |
List of Link |
3.64. List of Title File Resources
| Field Name | Description | Type | Format | Nullable |
|---|---|---|---|---|
next |
Token that can be used as the 'start' value to retrieve another group of results |
String |
||
titleFileResources |
List of Title File Resource |
|||
links |
List of Link |
3.65. Link
| Field Name | Description | Type | Format | Nullable |
|---|---|---|---|---|
rel |
A relationship name. |
String |
enum [self, coverimage, thumbnail, download, history, titleSource, replacement, submitter] |
|
href |
An absolute or relative URI for a resource request. |
String |
||
title |
Descriptive text that could be used as link text. |
String |
||
type |
Media type that this link is expected to return. |
String |
3.66. Title Metadata Detail
| Field Name | Description | Type | Format | Nullable |
|---|---|---|---|---|
bookshareId |
Unique identifier of the title |
String |
||
title |
Title of the book or reading material |
String |
||
subtitle |
Subtitle of the book or reading material |
String |
||
authors |
Deprecated - Author names of the title |
List of Name |
||
seriesTitle |
Title of the series to which the book belongs, if applicable |
String |
||
seriesSubtitle |
Subtitle of the series to which the book belongs |
String |
||
seriesNumber |
Number of the book within the series to which it belongs |
String |
||
isbn13 |
ISBN of the book or reading material |
String |
||
available |
True if the title is potentially available to users. See 'formats' for the ways the current user is allowed to request the title |
Boolean |
||
relatedIsbns |
ISBNs of books related to the title |
List of String |
||
publishDate |
The date this title was added to the collection |
Date |
date-time |
|
copyrightDate |
The copyright year of this title |
String |
year |
|
copyrightHolder |
The copyright owner of the book or reading material |
String |
||
copyright |
Deprecated - The copyright owner of the book or reading material |
String |
||
publisher |
The publisher of the book or reading material |
String |
||
synopsis |
Synopsis of the title |
String |
||
adultContent |
True if the title contains adult content |
Boolean |
||
usageRestriction |
||||
categories |
Categories of the title |
List of Category |
||
languages |
Languages of the title. The value will be a three-character ISO 639-2 alpha-3 language code |
List of String |
||
grades |
Grades for which the title is appropriate |
List of Grade |
||
formats |
Formats in which the title is available |
List of Format |
||
externalFormats |
Formats in which the title is available, but which are not deliverable by the API. Access to these formats must be negotiated with the site responsible for the title. |
List of Format |
||
titleContentType |
General type of content found in this title. Most titles will be text, but specialized titles could be primarily content like music scores or graphic images. |
String |
||
countries |
Countries to which this title is restricted for distribution. The values should be a two-character ISO 3166 alpha-2 country code. |
List of String |
||
originCountry |
Country from which the title originated. The value should be a two-character ISO 3166 alpha-2 country code. |
String |
||
numPages |
Number of pages in this title |
Integer |
||
replacementId |
Identifier of the title that replaced this one, if any |
String |
||
allowRecommend |
True if this title can be part of a recommendation set |
Boolean |
||
externalCategoryCode |
A proprietary category designation |
String |
||
edition |
Edition of the book or reading material |
String |
||
readingAgeMinimum |
The minimum reading age for which the book is recommended |
Integer |
||
readingAgeMaximum |
The maximum reading age for which the book is recommended |
Integer |
||
lexileCode |
The 2-letter Lexile code describing additional information about the readability of the book. |
String |
||
lexileNumber |
The numeric Lexile measure describing the readability of the book, followed by an 'L'. |
String |
||
titleAccessAlerts |
List of informational alerts if the requesting user is not allowed to download or read this title. See the list of title access alert codes for the set of possible values. |
List of Alert |
||
nimac |
True if this title came from the NIMAC, which has special meaning to US school members. |
Boolean |
||
numImages |
Number of images in this title |
Integer |
||
composers |
Deprecated - Composer names of the sheet music |
List of Name |
||
lyricists |
Deprecated - Lyricists of the sheet music |
List of Name |
||
arrangers |
Deprecated - Arrangers of the sheet music |
List of Name |
||
translators |
Deprecated - Translators of the sheet music |
List of Name |
||
contributors |
Contributors to the title |
List of Contributor |
||
contentWarnings |
List of content warnings for the title |
List of content_warning_values |
||
instruments |
Instruments of the sheet music |
String |
||
vocalParts |
Vocal parts of the sheet music |
String |
||
opus |
Opus of the sheet music |
String |
||
movementNumber |
Movement number of the sheet music |
String |
||
movementTitle |
Movement title of the sheet music |
String |
||
key |
Key of the sheet music |
String |
||
musicLayout |
Music layout of the sheet music |
String |
||
musicScoreType |
Score type of the sheet music |
String |
||
hasChordSymbols |
Chord symbols of the sheet music |
String |
||
notes |
Any general notes for the title |
String |
||
status |
Status of the title |
String |
enum [live, withdrawn, new, beingEdited, proofreadValid, proofreadRejected, converted, reprocess, validated, userSubmitted, publisherSubmitted, removed] |
|
marrakeshAvailable |
True if this title is available under the Marrakesh Treaty |
Boolean |
||
marrakeshPODException |
True if this title is available under the Marrakesh Proof of Disability exception |
Boolean |
||
artifacts |
Additional information, if any, about the artifacts available for this title |
List of Artifact Metadata |
||
site |
The site with which the title is associated |
String |
||
owner |
The owner of the document |
String |
||
allows |
Operations allowed: PUT, for Collection Assistants |
List of String |
enum [PUT] |
|
links |
List of Link |
3.67. Title Metadata Summary
| Field Name | Description | Type | Format | Nullable |
|---|---|---|---|---|
bookshareId |
Unique identifier of the title |
String |
||
title |
Title of the book or reading material |
String |
||
subtitle |
Subtitle of the book or reading material |
String |
||
authors |
Deprecated - Author names of the title |
List of Name |
||
seriesTitle |
Title of the series to which the book belongs, if applicable |
String |
||
seriesNumber |
Number of the book within the series to which it belongs |
String |
||
isbn13 |
ISBN of the book or reading material |
String |
||
available |
True if the title is potentially available to users. See 'formats' for the ways the current user is allowed to request the title |
Boolean |
||
publishDate |
The date this title was added to the collection |
Date |
date-time |
|
copyrightDate |
The copyright year of this title |
String |
year |
|
synopsis |
Synopsis of the title |
String |
||
categories |
Categories of the title |
List of Category |
||
languages |
Languages of the title. The value will be a three-character ISO 639-2 alpha-3 language code |
List of String |
||
formats |
Formats in which the title is available |
List of Format |
||
externalFormats |
Formats in which the title is available, but which are not deliverable by the API. Access to these formats must be negotiated with the site responsible for the title. |
List of Format |
||
titleContentType |
General type of content found in this title. Most titles will be text, but specialized titles could be primarily content like music scores or graphic images. |
String |
||
readingAgeMinimum |
The minimum reading age for which the book is recommended |
Integer |
||
readingAgeMaximum |
The maximum reading age for which the book is recommended |
Integer |
||
lexileCode |
The 2-letter Lexile code describing additional information about the readability of the book. |
String |
||
lexileNumber |
The numeric Lexile measure describing the readability of the book, followed by an 'L'. |
String |
||
nimac |
True if this title came from the NIMAC, which has special meaning to US school members. |
Boolean |
||
numImages |
Number of images in this title |
Integer |
||
composers |
Deprecated - Composer names of the sheet music |
List of Name |
||
lyricists |
Deprecated - Lyricists of the sheet music |
List of Name |
||
arrangers |
Deprecated - Arrangers of the sheet music |
List of Name |
||
translators |
Deprecated - Translators of the sheet music |
List of Name |
||
contributors |
Contributors to the title |
List of Contributor |
||
contentWarnings |
List of content warnings for the title |
List of content_warning_values |
||
instruments |
Instruments of the sheet music |
String |
||
vocalParts |
Vocal parts of the sheet music |
String |
||
site |
The site with which the title is associated |
String |
||
owner |
The owner of the document |
String |
||
allows |
Operations allowed: PUT, for Collection Assistants |
List of String |
enum [PUT] |
|
links |
List of Link |
3.68. List of Title Metadata Summaries
| Field Name | Description | Type | Format | Nullable |
|---|---|---|---|---|
message |
||||
totalResults |
The number of results found that match the search criteria |
Integer |
||
next |
Token that can be used as the 'start' value to retrieve another group of results |
String |
||
limit |
Maximum number of results included in this set |
Integer |
||
titles |
List of Title Metadata Summary |
|||
authorFacets |
The values can be used with the authorFilter parameter to reduce the number of results. |
List of Facet |
||
categoryFacets |
The values can be used with the categories parameter to reduce the number of results. |
List of Facet |
||
allows |
Operations allowed: POST = submit title |
List of String |
enum [POST] |
|
links |
List of Link |
3.69. Usage Restriction
| Field Name | Description | Type | Format | Nullable |
|---|---|---|---|---|
name |
Descriptive name of the usage restriction |
String |
||
restrictionCode |
Allowed values for the usage restriction |
String |
enum [copyright, publicDomain, creativeCommons] |
|
usageRestrictionId |
Unique identifier |
String |
3.70. User Identity
| Field Name | Description | Type | Format | Nullable |
|---|---|---|---|---|
username |
Identifying name associated with the account |
String |
||
name |
||||
links |
List of Link |
3.71. User Name
| Field Name | Description | Type | Format | Nullable |
|---|---|---|---|---|
userName |
User name of the user account |
String |
Appendix A: Alert Codes
A.1. Title Access Alerts
The following are the set of possible alert codes that might be returned in title metadata details identifying reasons that a title is not available to the current user.
| Alert code | Description |
|---|---|
AdultTitleNotAllowed |
This title contains adult content and is not available to minors. |
AuthenticationRequired |
Authentication is required to access this title. |
BrfLanguageNotSupported |
BRF download is not available for this title’s language. |
BrfMultipleLanguageNotSupported |
BRF download is not available for titles whose content is in multiple languages. |
DownloadCountExceededMonth |
The user has reached their 30-day download limit. |
DownloadCountExceededSubscription |
The user has reached their subscription download limit. |
GeographicRestriction |
This title is not available for download in the user’s state or country, or their address information is incomplete. |
GeographicRestrictionNewsline |
This title is only available to residents of states that support the NFB-NEWSLINE service. |
NimacNotAllowed |
This title is NIMAC restricted and the user does not have an IEP. |
NimacOrganizationNotAllowed |
This title is sourced from the NIMAC and is restricted to K-12 schools serving students with public IEPs. |
OrganizationAgreementRequired |
The primary contact of the organization must sign and return the organizational agreement. |
OrganizationBookBlockLimit |
The organization has reached their purchased download limit. |
OrganizationStatusNotApproved |
The organization’s access is currently suspended. |
OrganizationSubscriptionRequired |
The organization needs to purchase a subscription. |
SponsorCannotDownloadForSelf |
An organization sponsor can only download for members of the organization, not themself. |
TitleNotAvailableForDemo |
This title is not available for demo accounts. |
TitleWrongStatus |
This title is currently not available for download. |
UnauthorizedOrganizationMember |
The organization member does not have access to this title. A sponsor must add the title to a reading list. |
UnauthorizedUser |
The user is not authorized to download this title. |
UnknownError |
General error, with specifics in the alert message text. |
UserAgreementRequired |
The user must complete their Bookshare membership agreement in order to download the title. |
UserDisabilityStatusRequired |
The user must submit a Proof of Disability in order to download the title. |
UserStatusInactive |
The user’s account is not active. |
UserSubscriptionExpired |
The user’s subscription has expired. |
UserSubscriptionRequired |
An active subscription is required to download this title. |