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
• Data Definitions
• Request Headers
  • Request Header - vbid example
  • Request Header - toc example
  • Request Header - include_details accessibility - example
  • Request Header - type - example
• Response
  • Response Body - vbid example
  • Response Body - toc example
  • Response Body - accessibility example
  • Response Descriptions - default
  • Response Descriptions - include_details
    • Response Descriptions - metadata
    • Response Descriptions - subjects
    • Response Descriptions - identifiers
    • Response Descriptions - store
    • Response Descriptions - accessibility
  • How to utilize the TOC response
  • Error Codes

Verb/URI

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

Data Definitions

Request Headers

X-VitalSource-API-Key: ALLNUMBERSANDCAPS
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.

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.

Response Descriptions - metadata

Response Descriptions - subjects

Response Descriptions - identifiers

Response Descriptions - store

Response Descriptions - accessibility

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

• a11y/schema.org
• IDPF/a11y

 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