1. Overview

The Bookshare API v2 for Collection Management provides clients endpoints for Collection Assistant users to manage the set of titles which are part of their Site. The same conventions and general rules for API use apply here as they do to the public API for Bookshare users.

Collection Assistants are typically allowed to update properties of titles, both for titles that are visible to members and titles that have either been withdrawn, or are still being prepared for use. They can also see additional properties of titles, and have access to event history to see what processing has been done to a title. As part of their work to help bring titles into the collection, they will also have access to different stages in the processing pipeline as they work with publishers and other title providers to bring new content to the collection.

2. Endpoints

2.1. Collection Assistant - Periodicals

Administrative users have resources available that will let them manage periodical series and editions. These are similar in function to the title resources, but with differences related to the series nature of periodicals.

2.1.1. Update periodical series metadata

PUT /v2/periodicals/{seriesId}
Description

Update the series metadata for an existing periodical.

Parameters
Path Parameters
Name Description Required Schema Default

seriesId

ID of the Periodical series

X

String

null
Form Parameters
Name Description Required Schema Default

title

Title of the periodical series

-

String

null

issn

ISSN of the periodical series

-

String

null

description

Description of the periodical series

-

String

null

publisher

Publisher name for the periodical series

-

String

null

externalCategoryCode

External category code

-

String

null

categories

Bookshare categories, each sent as an individual parameter.

-

String

null

languages

Languages, each sent as an individual parameter.

-

String

null

seriesType

Type of periodical

-

enum [newspaper, magazine, journal]

null

countries

Countries to which this series is restricted for distribution. The values should be a two-character ISO 3166 alpha-2 country code.

-

String

null
Responses
HTTP Code Message Datatype

200

Periodical series metadata detail response

Periodical Series Metadata Summary

0

Unexpected error

Error
Example HTTP request
PUT /v2/periodicals/123 HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: api.bookshare.org
Content-Length: 194

title=USA+Today&issn=0734-7456&description=USA+Today&languages=eng&categories=Politics+and+Government&externalCategoryCode=extCode1&seriesType=newspaper&countries=US&countries=CA&api_key=abcdefg
Example HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 780

{
  "seriesId" : 123,
  "title" : "USA Today",
  "issn" : "0734-7456",
  "description" : "USA Today",
  "publisher" : "Gannett Company, Inc.",
  "seriesType" : "newspaper",
  "externalCategoryCode" : "extCode1",
  "categories" : [ {
    "name" : "POLITICAL SCIENCE / General",
    "description" : "POLITICAL SCIENCE / General",
    "categoryType" : "BISAC",
    "code" : "POL000000",
    "links" : [ ]
  } ],
  "languages" : [ "eng" ],
  "countries" : [ "US", "CA" ],
  "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' -i -X PUT \
    -d 'title=USA+Today&issn=0734-7456&description=USA+Today&languages=eng&categories=Politics+and+Government&externalCategoryCode=extCode1&seriesType=newspaper&countries=US&countries=CA&api_key=abcdefg'

2.1.2. Update periodical edition metadata

PUT /v2/periodicals/{seriesId}/editions/{editionId}
Description

Update the metadata of an existing periodical edition.

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
Form Parameters
Name Description Required Schema Default

editionName

The name of the periodical edition

-

String

null

publicationDate

The publication date of the periodical edition

-

date

null

expirationDate

The expiration date (if any) of the periodical edition

-

date

null
Responses
HTTP Code Message Datatype

200

Periodical edition metadata response

Periodical Edition

0

Unexpected error

Error
Example HTTP request
PUT /v2/periodicals/100/editions/1001 HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: api.bookshare.org
Content-Length: 98

editionName=Los+Angeles+Times&publicationDate=2018-01-01&expirationDate=2020-01-01&api_key=abcdefg
Example HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 521

{
  "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}"
  } ]
}
Example Curl request
$ curl 'https://api.bookshare.org/v2/periodicals/100/editions/1001' -i -X PUT \
    -d 'editionName=Los+Angeles+Times&publicationDate=2018-01-01&expirationDate=2020-01-01&api_key=abcdefg'

2.1.3. Withdraw a periodical edition

DELETE /v2/periodicals/{seriesId}/editions/{editionId}
Description

Withdraw a periodical edition.

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
Responses
HTTP Code Message Datatype

202

Request has been received, and will be processed.

Status

0

Unexpected error

Error
Example HTTP request
DELETE /v2/periodicals/100/editions/1001 HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: api.bookshare.org
Content-Length: 15

api_key=abcdefg
Example HTTP response
HTTP/1.1 202 Accepted
Content-Type: application/json
Content-Length: 84

{
  "key" : "SUCCESS",
  "messages" : [ "Periodical withdrawal request received" ]
}
Example Curl request
$ curl 'https://api.bookshare.org/v2/periodicals/100/editions/1001' -i -X DELETE \
    -d 'api_key=abcdefg'

2.2. Collection Assistant - Titles

Administrative users have resources available that will let them manage the collection, either by adding or removing titles, or by manipulating their metadata. This could include withdrawing live titles, publishing pending titles, or reviewing proofread scans. Collection Assistants can perform these functions, only restricted to the titles that are associated with their site.

2.2.1. Search for titles across the catalog

GET /v2/catalog
Description

For allowed roles, you can ask for titles that might not be visible to regular users, such as those that were once in the collection, but have since been removed. This allows adminstrators to manage the wider collection of titles. Like with the general title search, 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

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

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

titleStatus

Limit results to those with the given status.

-

enum [live, withdrawn, new, beingEdited, proofreadValid, proofreadRejected, converted, reprocess, validated, userSubmitted, publisherSubmitted, removed]

null

startUpdatedDate

Start date for a filtered range of results. Uses the date-time notation as described in the dates section.

-

Date

null

endUpdatedDate

End date for a filtered range of results. Uses the date-time notation as described in the dates section.

-

Date

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 [relevance, title, author, updatedDate, copyrightDate]

[title]

direction

Direction for sorting.

-

enum [asc, desc]

[asc]
Responses
HTTP Code Message Datatype

200

Title metadata collection response

List of Title Metadata Complete Records

0

Unexpected error

Error
Example HTTP request
GET /v2/catalog?country=CA&titleStatus=live&startUpdatedDate=2020-01-01T00%3A00%3A00Z&endUpdatedDate=2020-02-01T00%3A00%3A00Z&limit=1&sortOrder=updatedDate&direction=desc&api_key=abcdefg HTTP/1.1
Host: api.bookshare.org
Example HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 5153

{
  "limit" : 1,
  "next" : "abcde",
  "totalResults" : 20123,
  "allows" : null,
  "titles" : [ {
    "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,
    "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" : "",
    "numPages" : null,
    "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" : null,
      "dateAdded" : "2018-09-01T00:00:00Z"
    } ],
    "edition" : null,
    "opus" : null,
    "movementNumber" : null,
    "movementTitle" : null,
    "key" : null,
    "musicScoreType" : null,
    "hasChordSymbols" : false,
    "marrakeshAvailable" : null,
    "marrakeshPODException" : null,
    "notes" : null,
    "status" : "live",
    "lastUpdated" : "2020-02-24T00:00:00Z",
    "dtbookSize" : 1,
    "submitter" : "101",
    "proofreader" : null,
    "titleSource" : 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"
    } ]
  } ],
  "authorFacets" : null,
  "categoryFacets" : null,
  "message" : null,
  "links" : [ {
    "rel" : "self",
    "href" : "https://api.bookshare.org/v2/catalog?country=CA&titleStatus=live&startUpdatedDate=2020-01-01T00:00:00Z&endUpdatedDate=2020-02-01T00:00:00Z&limit=1&sortOrder=updatedDate&direction=desc&api_key=abcdefg"
  }, {
    "rel" : "next",
    "href" : "https://api.bookshare.org/v2/catalog?country=CA&titleStatus=live&startUpdatedDate=2020-01-01T00:00:00Z&endUpdatedDate=2020-02-01T00:00:00Z&limit=1&sortOrder=updatedDate&direction=desc&api_key=abcdefg&start=abcde"
  } ]
}
Example Curl request
$ curl 'https://api.bookshare.org/v2/catalog?country=CA&titleStatus=live&startUpdatedDate=2020-01-01T00%3A00%3A00Z&endUpdatedDate=2020-02-01T00%3A00%3A00Z&limit=1&sortOrder=updatedDate&direction=desc&api_key=abcdefg' -i -X GET

2.2.2. Get a list of title history events

GET /v2/titles/{bookshareId}/history
Description

Get a list of events that mark transitions or updates to the given title and its artifacts. For example, these events might tell when a particular metadata value changed, or when an audio artifact was created.

Parameters
Path Parameters
Name Description Required Schema Default

bookshareId

Unique identifier of a title

X

String

null
Responses
HTTP Code Message Datatype

200

Title history event collection response

List of Title History Events

0

Unexpected error

Error
Example HTTP request
GET /v2/titles/1343455/history?api_key=abcdefg HTTP/1.1
Host: api.bookshare.org
Example HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 347

{
  "titleEvents" : [ {
    "action" : "PUBLISH",
    "comment" : "Title published",
    "date" : "2019-12-01T00:00:00Z",
    "format" : {
      "formatId" : "DAISY",
      "name" : "DAISY"
    },
    "personName" : "Sally Smith"
  } ],
  "links" : [ {
    "rel" : "self",
    "href" : "https://api.bookshare.org/v2/titles/1343455/history"
  } ]
}
Example Curl request
$ curl 'https://api.bookshare.org/v2/titles/1343455/history?api_key=abcdefg' -i -X GET

2.2.3. Update title metadata

PUT /v2/titles/{bookshareId}
Description

Update a title’s metadata. This includes title, author, ISBN and other properties. This submits a request that will be processed at some point in the future. The title history event list will include an entry reflecting this request and showing when it was applied.

Parameters
Path Parameters
Name Description Required Schema Default

bookshareId

Unique identifier of a title.

X

String

null
Form Parameters
Name Description Required Schema Default

title

Main title of the book or reading material.

-

String

null

subtitle

Subtitle of the book or reading material.

-

String

null

isbn13

ISBN of the book or reading material. This can be either ISBN-10 or ISBN-13, but it will be converted to ISBN-13.

-

String

null

authors

Author names for the title. Enter each person or entity as a separate instance of this parameter.

-

String

null

abridgers

People named as 'abridged by'. Enter each person or entity as a separate instance of this parameter.

-

String

null

adapters

People named as 'adapted by'. Enter each person or entity as a separate instance of this parameter.

-

String

null

arrangers

People named as 'arranged by'. Enter each person or entity as a separate instance of this parameter.

-

String

null

composers

People named as 'composer' of a musical score. Enter each person or entity as a separate instance of this parameter.

-

String

null

coWriters

People named as 'written with'. Enter each person or entity as a separate instance of this parameter.

-

String

null

editors

People named as 'editor' or 'edited by'. Enter each person or entity as a separate instance of this parameter.

-

String

null

epilogueBys

People named as 'epilogue by'. Enter each person or entity as a separate instance of this parameter.

-

String

null

forewardBys

People named as 'foreward by'. Enter each person or entity as a separate instance of this parameter.

-

String

null

introductionBys

People named as 'introduction by'. Enter each person or entity as a separate instance of this parameter.

-

String

null

lyricists

People named as 'lyricist' of a musical score. Enter each person or entity as a separate instance of this parameter.

-

String

null

transcribers

People named as 'transcriber' of a Braille title. Enter each person or entity as a separate instance of this parameter.

-

String

null

translators

People named as 'translated by'. Enter each person or entity as a separate instance of this parameter.

-

String

null

synopsis

Descriptive summary of the title.

-

String

null

seriesTitle

Title of the series to which the book belongs, if applicable.

-

String

null

seriesSubtitle

Subtitle of the series to which the book belongs, if applicable.

-

String

null

seriesNumber

Number of the book within the series to which it belongs.

-

String

null

copyrightHolder

The copyright owner of the book or reading material.

-

String

null

copyrightDate

The copyright year of the book or reading material.

-

Integer

null

edition

The edition name, if any, of the title.

-

String

null

readingAgeMinimum

The minimum reading age for which the content is recommended.

-

Integer

null

readingAgeMaximum

The maximum reading age for which the content is recommended.

-

Integer

null

adultContent

True if the title contains adult content.

-

Boolean

null

allowRecommend

True if the title should be a candidate for the recommendation engine.

-

Boolean

null

numPages

Number of pages in this title.

-

Integer

null

publisher

The publisher of the book or reading material.

-

String

null

categories

Bookshare categories to which the title belongs. For choices, see the category listing endpoint.

-

String

null

bisacCategories

BISAC categories to which the title belongs. For choices, see the list of BISAC codes.

-

String

null

countries

Countries to which this title is restricted for distribution. The values should be a two-character ISO 3166 alpha-2 country code.

-

String

null

languages

Languages of the title. The value will be a three-character ISO 639-2 alpha-3 language code.

-

String

null

grades

Code value of the grades for which the content is appropriate. Values are from ONIX codelist 77 for US grades, BIC for UK grades.

-

String

null

contentWarnings

Content warnings attached to the title.

-

enum [contentWarning, sex, violence, drugs, language, intolerance, adult, unrated]

null

relatedIsbns

ISBNs of other formats or renderings of the title.

-

String

null

usageRestriction

Usage restriction on the title, in terms of licensing.

-

enum [copyright, publicDomain, creativeCommons]

null

externalCategoryCode

A code that maps to a category scheme in an external system. This can be used to track categories that Bookshare does not recognize.

-

String

null

musicScoreType

If the content is a music score, the type of score it represents.

-

enum [fullScore, openScore, singleLine]

null

hasChordSymbols

If the content is a music score, true if the content includes musical chord symbols.

-

Boolean

null

instruments

If the content is a music score, the names of any musical instruments that it covers.

-

String

null

key

If the content is a music score, the musical key in which the score is written.

-

String

null

movementNumber

If the content is a music score, the descriptive number of the musical movement.

-

String

null

movementTitle

If the content is a music score, the descriptive title of the movement.

-

String

null

opus

If the content is a music score, the descriptive number of the opus.

-

String

null

vocalParts

If the content is a vocal score, the letters representing the vocal parts it covers. This can be some combination of the letters S, A, T and B.

-

String

null

notes

Text to place in the metadata record of the title, describing particular features of the title for other Collection Assistants to see.

-

String

null

marrakeshEligible

True if the title would be eligible to be shared with qualifying Marrakesh Treaty countries when the title’s country of origin has implemented the Marrakesh Treaty.

-

Boolean

null

marrakeshPODException

True if the title has a Marrakesh Proof of Disability exception.

-

Boolean

null

availableToDemo

True if the title is available to download by special user accounts set up for demonstration purposes.

-

Boolean

null

availableWorldwide

True if the title is available to users in any country.

-

Boolean

null

states

States to which this title is restricted for distribution. The value should be either a two-character postal abbreviation or an ISO 3166-2 subdivision code for the country. This field is only relevant for subdivisions of the US and Canada. Enter each state as a separate instance of this parameter.

-

String

null

comments

Text to place in the history of updates to the title, describing how or why the current changes are being made.

-

String

null

hasEmbeddedImageDescriptions

True if the title has the image description in the text content, rather than in standard XML or HTML markup.

-

Boolean

null

quality

Rating of how well the title reflects the content and structure of the original material.

-

enum [publisher, excellent, good, fair]

null

originCountry

The origin country of the title. The value should be a two-character ISO 3166 alpha-2 country code.

-

String

null

productIdentifier

Unique identifier of the title within the collection. This could be a standard identifier, such as ISBN, or a custom identifier, so long as it is unique.

-

String

null

lexileCode

The two-letter Lexile code of the title describing the type of book and age appropriateness.

-

String

null

lexileNumber

The Lexile measure representing the title’s readability.

-

String

null

nimacRestricted

True if the title is NIMAC restricted.

-

Boolean

null
Responses
HTTP Code Message Datatype

202

Request has been received, and will be processed.

Status

0

Unexpected error

Error
Example HTTP request
PUT /v2/titles/1041744 HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: api.bookshare.org
Content-Length: 196

editors=Jane+Doe&editors=John+Smith&numPages=256&seriesTitle=Adventures+of+Tom+and+Huck&seriesNumber=1&categories=Literature+and+Fiction&categories=Teens&usageRestriction=copyright&api_key=abcdefg
Example HTTP response
HTTP/1.1 202 Accepted
Content-Type: application/json
Content-Length: 74

{
  "key" : "SUCCESS",
  "messages" : [ "Update requested for 1041744" ]
}
Example Curl request
$ curl 'https://api.bookshare.org/v2/titles/1041744' -i -X PUT \
    -d 'editors=Jane+Doe&editors=John+Smith&numPages=256&seriesTitle=Adventures+of+Tom+and+Huck&seriesNumber=1&categories=Literature+and+Fiction&categories=Teens&usageRestriction=copyright&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. 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

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

Name

accessibilityMetadata

Accessibility Metadata

dateAdded

Date that the artifact was originally added to the collection

Date

date-time

3.5. 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.6. Content Warning Values

Enum Values

contentWarning

sex

violence

drugs

language

intolerance

adult

unrated

3.7. Contributor

Field Name Description Type Format Nullable

name

Contributor 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.8. 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.9. Error

Field Name Description Type Format Nullable

key

String

messages

List of String

3.10. 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.11. 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
Field Name Description Type Format Nullable

rel

A relationship name

String

href

An absolute or relative URI for a resource request

String

3.13. 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.14. 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.15. 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.16. Periodical Edition Summary

Field Name Description Type Format Nullable

editionId

Unique identifier of the periodical edition

String

editionName

Name of the edition

String

3.17. 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

Periodical Edition Summary

links

List of Link

3.18. Status

Field Name Description Type Format Nullable

key

String

messages

List of String

X

3.19. Title History Event

Field Name Description Type Format Nullable

date

Date the action was performed

Date

date-time

personName

Person who performed the action

String

action

Action that was performed

String

comment

Comments about the action performed

String

format

The format identifier of the artifact for which the event occurred

String

3.20. List of Title History Events

Field Name Description Type Format Nullable

events

List of Title History Event
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.22. Title Metadata Complete Record

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

Usage Restriction

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

numPages

Number of pages in this title

Integer

replacementId

Identifier of the title that replaced this one, if any

String

withdrawalDate

The date this title was removed from the collection

Date

date-time

lastUpdated

The date this title was most recently updated, either with changed metadata, a new artifact, or a changed status

Date

date-time

numImages

Number of images in this title

Integer

dtbookSize

Number of bytes in the DTBook content file of the DAISY artifact

Long

int64

submitter

An identifier of the person who submitted the original scanned title

String

proofreader

An identifier of the person who proofread the original scanned title

String

titleSource

The publisher or distributor who submitted the original title artifact

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

nimac

True if this title came from the NIMAC, which has special meaning to US school members.

Boolean

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

site

The site with which the title is associated

String

owner

The owner of the document

String

artifacts

Additional information, if any, about the artifacts available for this title

List of Artifact Metadata

allows

Operations allowed: PUT, for Collection Assistants

List of String

enum [PUT]

links

List of Link

3.23. List of Title Metadata Complete Records

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

titles

List of Title Metadata Complete Record

allows

Operations allowed: None

List of String

links

List of Link

3.24. 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