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 specialized TOC and ? requests.

Verb/URI

GET https://api.vitalsource.com/v4/products/:vbid
GET https://api.vitalsource.com/v4/products/:vbid/toc
GET https://api.vitalsource.com/v4/products/:vbid?include_details=subjects,metadata

Data Definitions

Element/field Type Description Example
vbid String VitalBook Identifier, a unique identifier for the asset L-999-70030
 kind String The type of asset/product including book, chapter, title, online resource, online resource bundle book
print_isbn_canonical Integer Print ISBN of asset returned

9780321775658

eisbn_canonical Integer eISBN of asset returned 9781416064473
title String Asset title Fall of the House of Usher
format String Format of the book; dashML, pbk, pdf, ePub are valid returns. ePub
publisher String Name of the publisher Hayes Barton Press
edition Integer Edition of the book 2
contributors - name String Names of the contributors for the asset Kordower, Jeffrey; Tuszynski, Mark H.
contributors - type String Type of contributor  
language String Language of the asset English
created

ISO-8601 date/time

Date the asset was created

2011-05-25T14:40:25Z

off_sale_date  ISO-8601 date Date the asset will be removed from distribution 2017-09-25
print_restrictions Integer Display text for printing rules 10
copy_restrictions Integer Display text for copying rules 10
metadata URL Additional API call to gather additional metadata about the asset

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

cover_image URL URL for the cover image of the asset

https://covers.vitalbook.com/vbid/L-999-70030/width/480

table_of_contents URL Additional API call to return the Table of Contents for the asset

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

store_url URL Store URL for the asset

https://www.vitalsource.com/textbooks?term=L99970030

previous edition String Previous edition of the asset 0-397-58401-6
next_edition String Next edition of the asset 0-323-03339-3
ancillary String    
sales_rights Array Country codes where content can be sold US
exclude_sales_rights Array Country codes where content cannot be sold TR
variants Array Additional products based on the asset  
duration String Duration for the downloadable version of the product variant, all values are returned as number of days or perpetual perpetual
online_duration String Duration for the online version of the product variant, all values are returned as number of days or perpetual  365
sku String Unique product SKU for the product variant; this will be used to make additional API calls to create codes. 0-323-01320-1
type String Describes the type of product Package
distributable Boolean 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. true
prices Array Pricing details for the specific product variant  
type String Type of pricing category for the product variant digital-list-price
value String Price of the product variant 67.95
currency String Country code of the currency USD
discount_code String The discount code returned from publishers, typically from an ONIX feed 091254
territory String    
updated

ISO-8601 date/time

Date the product variant was last updated 2017-05-01T19:55:18Z
contents Array This will return the SKUs that are included in a package "9781929629084",
"9781935589440"
       
Response Groups      
subjects      
schema String Subject classification schema bisac
code String Subject code MED068000
name String Subject Name Pathophysiology
       
metadata      
description String The description of the asset This title is from the Hayes Barton Press "Originals" series, a collection of classic fiction and nonfiction works from world literature published…
sort_title String Sort title of the asset Essentials of Oral Histology and Embryology: A Clinical Approach
copyright_date String Date of copyright for the asset 2003
publication_date String Date of publication for the asset 1899
page_count Integer Page count of the asset (if provided by the publisher) 25
imprint_name String Name of the imprint of the publisher McGraw-Hill Higher Education (US)
parent_isbn String If the asset is a child to a parent asset (ex. single chapter of a book) this value is the parent asset 9780073403458
publisher_list_price String The publisher provided list price of the asset 99.95
       
identifiers      
isbn_canonical String Canonical ISBN of the asset 0721667538
isbn_10 String ISBN 10 of the asset 0721689663
isbn_13 String ISBN 13 of the asset 9780721689661
e_isbn String eISBN of the asset 9781416064473
       
accessibility      
accessibility_options Array Nested array of accessibility features of the current asset; null if no accessibility options have been specified.
"accessibility_options": {
    …
}

 

Request Headers

X-VitalSource-API-Key: ABCDEFGHIJKLMNOP
Content-Type: application/json
  • Replace Alphabet characters with your API key.
  • Content-Type header can specify JSON or XML outputs

Request Parameters

vbid

string

VitalBook Identifier (VBID) this is the unique identifier for the title your are requesting. Your available vbids can be found by first making the v4/products/ request

/v4/products/:vbid
vbid/toc

string=vbid

JSON format of title TOC as sent to VitalSource by the publisher

/v4/products/:vbid/toc
include_details

comma separated list

Valid groups: subjects,metadata,identifiers,accessibility

/v4/products?include_details=subjects,metadata

 

Response

curl -X GET -H "Content-Type: application/xml" -H "X-VitalSource-API-Key: ABCDEFGHIJKLMNOP" -H "Accept: application/xml" -H "Cache-Control: no-cache" "https://api.vitalsource.com/v4/products/L-999-70030.xml"
HTTP Code: 200
<?xml version="1.0" encoding="UTF-8"?>
<products>
<vbid>L-999-70030</vbid>
<kind>great book</kind>
<identifiers>
<print-isbn-canonical nil="true"/>
<eisbn-canonical nil="true"/>
</identifiers>
<title>Fall of the House of Usher</title>
<format>ePub</format>
<publisher>Hayes Barton Press</publisher>
<edition type="integer">0</edition>
<contributors type="array">
<contributor>
<name>Edgar Allan Poe</name>
<type nil="true"/>
</contributor>
</contributors>
<language>English</language>
<created type="dateTime">2006-03-04T06:20:36Z</created>
<off-sale-date nil="true"/>
<print-restrictions type="integer">-1</print-restrictions>
<copy-restrictions type="integer">-1</copy-restrictions>
<resource-links>
<metadata>https://api.vitalsource.com/v4/products/L99970030</metadata>
<cover-image>https://covers.vitalbook.com/vbid/L-999-70030/width/480</cover-image>
<table-of-contents>https://api.vitalsource.com/v4/products/L99970030/toc</table-of-contents>
<store-url>https://www.vitalsource.com/textbooks?term=L99970030</store-url>
</resource-links>
<related-products>
<previous-edition nil="true"/>
<next-edition nil="true"/>
<ancillary nil="true"/>
</related-products>
<sales-rights type="array">
<sales-right>WORLD</sales-right>
</sales-rights>
<exclude-sales-rights type="array"/>
<variants type="array">
<variant>
<duration>perpetual</duration>
<online-duration>365</online-duration>
<sku>L-999-70030</sku>
<type>Single</type>
<distributable type="boolean">true</distributable>
<prices type="array">
<price>
<type>publisher-list-price</type>
<value>5.00</value>
<currency>USD</currency>
<discount-code nil="true"/>
<territory nil="true"/>
</price>
<price>
<type>digital-list-price</type>
<value>2.50</value>
<currency>AUD</currency>
<discount-code nil="true"/>
<territory nil="true"/>
</price>
</prices>
<updated type="dateTime">2018-04-19T13:15:53Z</updated>
</variant>
</variants>
<contents type="array"/>
</products>
curl -X GET -H "Content-Type: application/json" -H "X-VitalSource-API-Key: ABCDEFGHIJKLMNOP" -H "Accept: application/json" -H "Cache-Control: no-cache" "https://api.vitalsource.com/v4/products/L-999-70030"
{
"vbid": "L-999-70030",
"kind": "ePub",
"identifiers": {
"print_isbn_canonical": "L99970030",
"eisbn_canonical": null
},
"title": "Fall of the House of Usher",
"format": "Page Fidelity",
"publisher": "Distributor Company",
"edition": 0,
"contributors": [
{
"name": "Edgar Allan Poe",
"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/L99970030",
"cover_image": "https://covers.vitalbook.com/vbid/L-999-70030/width/480",
"table_of_contents": "https://api.vitalsource.com/v4/products/L99970030/toc",
"store_url": "https://vitalsource.com/textbooks?term=L99970030"
},
"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": "0.99",
"currency": "USD",
"discount_code": null,
"territory": null
}
],
"updated": "2016-12-08T17:17:35Z",
}
],
"contents": []
}
require 'uri'
require 'net/http'

url = URI("https://api.vitalsource.com/v4/products/L-999-70030")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::GET.new(url)
request["content-type"] = 'application/json'
request["accept"] = 'application/json' request["x-vitalsource-api-key"] = 'ABCDEFGHIJKLMNOP' request["cache-control"] = 'no-cache' response = http.request(request) puts response.read_body
<?php

$client = new http\Client;
$request = new http\Client\Request;

$body = new http\Message\Body;

$request->setRequestUrl('https://api.vitalsource.com/v4/products/L-999-70030');
$request->setRequestMethod('GET');
$request->setBody($body);

$request->setHeaders(array(
  'x-vitalsource-api-key' => 'ABCDEFGHIJKLMNOP',
  'content-type' => 'application/json',
'accept' => 'application/json', )); $client->enqueue($request)->send(); $response = $client->getResponse(); echo $response->getBody(); ?php>
var client = new RestClient("https://api.vitalsource.com/v4/products/L-999-70030");
var request = new RestRequest(Method.GET);
request.AddHeader("x-vitalsource-api-key", "ABCDEFGHIJKLMNOP");
request.AddHeader("content-type", "application/json");
request.AddHeader("accept", "application/json");
IRestResponse response = client.Execute(request);
var http = require("https");

var options = {
  "method": "GET",
  "hostname": "api.vitalsource.com",
  "port": null,
  "path": "/v4/products/L-999-70030",
  "headers": {
    "content-type": "application/json",
    "x-vitalsource-api-key": "ABCDEFGHIJKLMNOP",
    "accept": "application/json",
  }
};

var req = http.request(options, function (res) {
  var chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    var body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();
import http.client

conn = http.client.HTTPSConnection("api.vitalsource.com")

headers = {
    'accept': "application/json",
    'content-type': "application/json",
    'x-vitalsource-api-key': "ABCDEFGHIJKLMNOP",
    }

conn.request("GET", "/v4/products/L-999-70030", headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))
HttpResponse<String> response = Unirest.post("https://api.vitalsource.com/v4/products/L-999-70030")
  .header("accept", "application/json")
  .header("content-type", "application/json")
  .header("x-vitalsource-api-key", "ABCDEFGHIJKLMNOP") 
.asString(); print(data.decode("utf-8"))
  

Response Groups

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

Parameter Value Description Example
include_details 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. View Data Dictionary include_details=identifiers
include_details metadata Returns additional metadata for a title. Descriptions, publication dates and other relevant metadata listed in the data dictionary. View Data Dictionary include_details=metadata
include_details subjects Returns BIASC categories for use of grouping titles in a users commerce platform. View Data Dictionary include_details=subjects
include_details 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. View Data Dictionary include_details=accessibility

 

Accessibility Options

If an asset has been enriched with metadata about the accessibility of the book file, it will show when requesting the asset's accessibility information. If no metadata has been set, the accessibility_options element will have a value of null. That doesn't, however, mean that the book has no accessibility options, just that they have not been set in the publisher's metadata.

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

In the accessibility_options array, each nested array has a two-part name separated by a colon. The first part lets you know which of the above links to look to for documentation. "schema:xxxx" is for ally/schema.org, and a11y:xxxx. For example:

"accessibility_options": {
"schema:accessMode": [
"visual",
"textual"
],
"schema:accessibilityHazard": [
"noSound",
"noFlashing",
"noMotionSimulation"
],
"a11y:certifiedBy": [
"Accessibility Testers Group"
]
}

The descriptions of visual and textual "access modes" can be found at a11y/schema.org. The definitions of what it means to be "certified" are found at 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

GET /v4/products/:vbid
403: Permission Denied
403: VST API keys are not valid for this endpoint. Please use a customer key.
404: Catalog not found
404: Product <vbid> not found.
422: Invalid currency: <currency>
 
GET /v4/products/:vbid/toc
403: Permission Denied
404: Book not found
423: Book is locked

See our full list of error codes and messages.

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

Comments

0 comments

Article is closed for comments.