GET v4/products/:vbid - Title, TOC, Metadata

The Products API is used to retrieve information about an individual title in your catalog. It includes the same data you would see in in v4/products, as well as information on eBook accessibility that is not available in the general catalog.We also offer /TOC ?include_details and  ?type requests.

Verb/URI

GET https://api.vitalsource.com/v4/products

Data Definitions

Name
Usage
Description
Data Type
Example
Required
vbid URL param The VitalBookID (VBID) for the title string

/L-999-70031

No
toc URL param Asset table of contents request string

/L-999-70031/toc

No
include_details URL param  Valid groups: metadata,subjects, identifiers,accessibility  string

v4/products?include_details=metadata,subjects

No
type URL param Specifiers: Packages,Rental,Single string

v4/products?type=Packages,Rental,Single

No 

 

Request Headers

X-VitalSource-API-Key: ALLCAPSANDNUMBERS
Accept: application/json

Request Header - vbid example

This request would return only the specified asset in payload

GET https://api.vitalsource.com/v4/products/L-999-70031

Request Header - toc example

This request would return the XML table of contents for the asset in payload

GET https://api.vitalsource.com/v4/products/L-999-70031/toc

Request Header - include_details - accessibility example

This request will add the accessibility array to the asset payload

GET https://api.vitalsource.com/v4/products/9781464182242?include_details=accessibility

Request Header - type -  example

This request will add variants to the asset payload

 

GET https://api.vitalsource.com/v4/products?type=Packages,Rental,Single

Response

Response Body - vbid example

{
"vbid": "L-999-70031",
"kind": "great book",
"identifiers": {
"print_isbn_canonical": "null",
"eisbn_canonical": null
},
"title": "Fantastic Fables",
"format": "ePub",
"publisher": "Hayes Barton Press",
"edition": 0,
"contributors": [
{
"name": "Ambrose Bierce",
"type": null
}
],
"language": null,
"created": "2006-03-04T06:20:36Z",
"off_sale_date": null,
"print_restrictions": -1,
"copy_restrictions": -1,
"resource_links": {
"metadata": "https://api.vitalsource.com/v4/products/L99970031",
"cover_image": "https://covers.vitalbook.com/vbid/L-999-70031/width/480",
"table_of_contents": "https://api.vitalsource.com/v4/products/L99970031/toc",
"store_url": "https://vitalsource.com/textbooks?term=L99970031"
},
"related_products": {
"previous_edition": null,
"new_edition": null,
"ancillary": null
},
"sales_rights": [],
"exclude_sales_rights": [],
"variants": [
{
"duration": "perpetual",
"online_duration": "365",
"sku": "L-999-70030",
"type": "Single",
"distributable": true,
"prices": [
{
"type": "digital-list-price",
"value": "5.00",
"currency": "USD",
"discount_code": null,
"territory": null
}
],
"updated": "2019-01-01T17:17:35Z",
}
],
"contents": []
}

Response Body - toc example (partial)

{
"table_of_contents": [
{
"title": "181 ORIGINAL FABLES",
"path": "/OPS/loc_001.xhtml",
"level": 1,
"cfi": "/6/4[idloc_001.xhtml-itemref]",
"kind": "document_container",
"page": "",
"data": []
},
{
"title": "The Moral Principle and the Material Interest",
"path": "/OPS/loc_002.xhtml",
"level": 2,
"cfi": "/6/6[idloc_002.xhtml-itemref]",
"kind": "document",
"page": "",
"data": []
},
{
"title": "The Crimson Candle",
"path": "/OPS/loc_003.xhtml",
"level": 2,
"cfi": "/6/8[idloc_003.xhtml-itemref]",
"kind": "document",
"page": "",
"data": []
},

Response Body - accessibility example


{
"vbid": "9781464182242",
"kind": "book",
"identifiers": {
"print_isbn_canonical": "9781464182235",
"eisbn_canonical": "9781464182242"
},
"title": "Psychology of Sex and Gender",
"format": "ePub",
"publisher": "Macmillan Higher Education",
"edition": 0,
"contributors": [
{
"name": "Susan Burns",
"type": null
}
],
"language": "English",
"created": "2018-12-03T20:49:05Z",
"off_sale_date": null,
"print_restrictions": 10,
"copy_restrictions": 2,
"resource_links": {
"metadata": "https://api.vitalsource.com/v4/products/9781464182242",
"cover_image": "https://covers.vitalbook.com/vbid/9781464182242/width/480",
"table_of_contents": "https://api.vitalsource.com/v4/products/9781464182242/toc",
"store_url": "https://www.vitalsource.com/textbooks?term=9781464182242"
},
....
Deleted section
....
"schema:accessibilityFeature": [
"longDescription",
"readingOrder",
"highContrastDisplay",
"displayTransformability/color",
"displayTransformability/font-size",
"index",
"mathML",
"unlocked",
"displayTransformability/font-family",
"displayTransformability/background color",
"alternativeText",
"displayTransformability/word-spacing",
"tableOfContents",
"printPageNumbers",
"displayTransformability/line-height",
"structuralNavigation",
"describedMath"
],
"schema:accessibilityHazard": [
"noSoundHazard",
"noMotionSimulationHazard",
"noFlashingHazard"
],
"schema:accessibilityAPI": [
"ARIA"
],
"schema:accessibilityControl": [
"fullKeyboardControl",
"fullMouseControl"
],
"schema:accessibilitySummary": {
"": "long description present using aria-describedby; Please enable reading of punctuation in your AT in order to hear necessary pedagogical information."
},
"a11y:certifiedBy": [
"Benetech"
],
"a11y:certifierCredential": [
"https://bornaccessible.org/certification/gca-credential/"
]
}
}

Response Descriptions - default

The standard response body, returned in your requested format.

Name
Description
vbid The VitalBookID (VBID) for the title
kind The type of asset/product including book, chapter, title, online resource, online resource bundle
print_isbn_canonical Print ISBN of asset returned
eisbn_canonical eISBN of asset returned
title Asset title
format Format of the book; dashML, pbk, pdf, ePub are valid returns.
publisher Name of the publisher
edition Edition of the book
contributors - name Names of the contributors for the asset
contributors - type Type of contributor
language Language of the asset
created Date the asset was created
off_sale_date Date the asset will be removed from distribution
print_restrictions Display text for printing rules
copy_restrictions Display text for copying rules
resource_links - metadata Additional API call to gather additional metadata about the asset
resource_links - cover_image URL for the cover image of the asset
resource_links - table_of_contents Additional API call to return the Table of Contents for the asset
resource_links - store_url VitalSource store URL for the asset
previous_edition Previous edition of the asset
next_edition Next edition of the asset 
ancillary  
sales rights array of country(s) where assets can be sold
exclude_sales_rights array of country(s) where assets cannot be sold
variants additional products based on the asset
variants - duration Duration for the downloadable version of the product variant, all values are returned as number of days or perpetual
variants - online_duration Duration for the online version of the product variant, all values are returned as number of days or perpetual
variants - sku Unique product SKU for the product variant; this will be used to make additional API calls to create codes
variants - type Type of product that is the variant
variants - distributable Value determines whether or not the items can be sold. Items will be in the product response with distributable = false due to deltas and identification of products that have been removed from sale. 
variants - prices - type Pricing details for the specific product variant
variants - prices - value Price of the product variant
variants - prices - currency Country code of the currency
variants - prices - discount_codes The discount code returned from publishers, typically from an ONIX feed
variants - prices - territory  
variants - updated Date the product variant was last updated
contents This will return the SKUs that are included in a package

 

Response Descriptions - include_details 

Include_details groups allow a user to request additional blocks of metadata. By default due to the amount of metadata provided for products the response will only include a smaller subset of data for ease of ingestion. If users would like additional book metadata, identifiers or subjects they can be requested using the include_details parameter below. You can request one to many of these response groups separated by a comma.

Name
Description
metadata Returns additional metadata for a title. Descriptions, publication dates and other relevant metadata listed in the data dictionary. 
identifiers Returns all of the alias identifiers VitalSource has related to a specific title. This can be used to help power your search index to allow lookup. These often will be the hardcover, spiral bound versions of ISBNs associated to the same digital title.
subjects Returns BIASC categories for use of grouping titles in a users commerce platform.
accessibility Returns the accessibility features for a title. Accessibility features are data like whether a title has audio captions or if images have descriptions for the visually impaired.

 

Response Descriptions - metadata

Name
Description
subtitle Subtitle of the asset
description Description of the asset
sort_title Sort title of the asset
publication_date Date of copyright for the asset
page_count Page count of the asset (if provided by the publisher)
imprint_name Name of the publisher imprint
parent_isbn If the asset is a child to a parent asset (ex. single chapter of a book) this value is the parent asset
publisher_list_price The publisher provided list price of the asset

 

Response Descriptions - subjects

Name
Description
schema Subject classification schema
code Subject code
name Subject name

 

Response Descriptions - identifiers

Name
Description
isbn_canonical Canonical ISBN of the asset
isbn_10 ISBN 10 of the asset
isbn_13 ISBN 13 of the asset
e_isbn eISBN of the asset

 

Response Descriptions - accessibility

The data that is returned in the accessibility_options array can be semantically understood by referencing the a11y w3c schemas here:

 

 How to utilize the TOC response

TOC's are built at ingestion by VitalSource based upon the XML submitted by the publisher of the content. Any update to the content by the publisher could change the TOC and break hard coded links. Best practice is to dynamically generate links, based upon the currently available version.

This is the example request

https://api.vitalsource.com/v4/products/9780926544406/toc

A TOC response will contain CFI structures, regardless of the book format. This example uses a PDF, whereas ePUB will have a longer URL in the cfi element.

{
"table_of_contents": [
{
"title": "E-book bonus materials",
"path": "/pages/403221165/content",
"level": 1,
"cfi": "/2",
"page": "2"
},
{
"title": "Contents",
"path": "/pages/403221170/content",
"level": 1,
"cfi": "/7",
"page": "7"
},
{
"title": "Chapter 1: Psychoactive Drugs: Classification and History",
"path": "/pages/403221174/content",
"level": 1,
"cfi": "/11",
"page": "11"
}

The base URL is "https://bookshelf.vitalsource.com/#/books/" then build your URL by adding the VBID and "/cfi" until you have "https://bookshelf.vitalsource.com/#/books/9780702051135/cfi" This becomes your base URL for this request.

Now parse the response to locate your chosen location, such as Chapter 1, then append the "cfi" element until you have "https://bookshelf.vitalsource.com/#/books/9780702051135/cfi/11" and you are now ready to utilize SSO redirects like this: 

<?xml version=\"1.0\" encoding=\"UTF-8\"?>
<redirect>
<destination>https://bookshelf.vitalsource.com/#/books/9780702051135/cfi/11</destination>
<brand>bookshelf.vitalsource.com</brand>
</redirect>

Error Codes

HTTP & Error messages 
Message
Notes
200

OK

 
400

Not Found

API key mismatch
403

Permission Denied

API key mismatch
403 Catalog not found Contact Customer Service
404

Product <vbid> not found.

make the default request and locate a valid vbid
404 Book not found  make the default request and locate a valid vbid 
422 Invalid currency: <currency> ISO-4217 currency code(s) 
423

Book is locked

TOC unavailable on this asset  
500

Internal Server Error

 

 

Was this article helpful?
0 out of 0 found this helpful

Comments

0 comments

Article is closed for comments.