GET v4/products - Read All

The Products API is used to retrieve and query the VitalSource catalog, which has more than a million titles available. Users can choose specific requests to filter results and also configure paging on how many records are returned per page. With this API you get access to data used by VitalSource to distribute, sell and link content including links to additional resources to retrieve other metadata for use within a users own commerce system.

How this guide is organized:

Learn the Basics What data is available in the base response, how to ingest data and what it means.
Response Groups Return additional product metadata for use in your commerce system. These are optional but return helpful information depending on what you're looking to do.
Prices Support for all currencies and price types as part of the catalog response.
Price Types What prices types exist and what they mean.
Deltas How to request products that have been added, updated or removed within a certain timeframe
Data Dictionary Data definitions and examples.

Learn the Basics

HTTP Verbs and URLs

GET /v4/products

Request Headers

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

Request Parameters

Parameter Value Description  Example
page integer Page number for the catalog request; default pagination is 1000 per page. Depending on the number of records in your distribution set, you will call multiple pages of data. Pages start at page 1. /v4/products?page=1
per_page integer: 1-1000  Valid values between 1 and 1,000; recommendation is to pull 1,000 at a time.

/v4/products?per_page=1000

from ISO-8601 date/time  

/v4/products?from=2017-01-17T15:09:05Z

until ISO-8601 date/time   /v4/products?until=2017-01-17T15:09:05Z
include_details

comma separated list

Valid groups: subjects, metadata, identifiers

/v4/products?include_details=subjects,metadata
currency

comma separated list

  /v4/products?currency=USD,GBP

Request 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"
HTTP Code: 200
<?xml version="1.0" encoding="UTF-8"?>
<products>
<num-items type="integer">16742</num-items>
<page type="integer">1</page>
<per-page type="integer">1000</per-page>
<total-pages type="integer">17</total-pages>
<items type="array">
<item>
<vbid>L-999-70030</vbid>
<kind>ePub</kind>
<identifiers>
<print-isbn-canonical>L99970030</print-isbn-canonical>
<eisbn-canonical nil="true"/>
</identifiers>
<title>Fall of the House of Usher</title>
  <format>Page Fidelity</format>
<publisher>Distributor Company</publisher>
<edition type="integer">0</edition>
<contributors type="array">
<contributor>
<name>Edgar Allan Poe</name>
<type nil="true"/>
</contributor>
</contributor>
<language nil="true"/>
<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://vitalsource.com/textbooks?term=L99970030</store-url>
</resource-links>
<related-products>
<previous-edition nil="true"/>
<new-edition nil="true"/>
<ancillary nil="true"/>
</related-products>
<sales-rights nil="true"/>
<exclude-sales-rights nil="true"/>
<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>digital-list-price</type>
<value>0.99</value>
<currency>USD</currency>
<discount-code nil="true"/>
<territory nil="true"/>
</price>
</prices>
<updated type="dateTime">2016-12-08T17:17:35Z</updated>
</variant>
</variants>
<contents type="array"/>
</item>
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"
{
"num_items": 16742,
"page": 1,
"per_page": 1000,
"total_pages": 17,
"items": [
{
"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")

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');
$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");
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",
  "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", headers)

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

print(data.decode("utf-8"))
HttpResponse<String> response = Unirest.post("https://api.vitalsource.com/v4/products")
  .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

Prices

Each product in a client's catalog can have many prices. Each price has the following attributes:

  • Type: Prices have "types," such as digital list price or print list price. When to use which price type as your selling price is dependent on your company's agreements with VST or your direct agreements with publishers. Please work with your company's Integrations Manager to develop your price-selection logic.
  • Value: The numeric value of the price.
  • Currency: The currency code of the price.
  • Discount Code: The discount code that can be applied to this product, if applicable.
  • Territory: Comma separated country codes based on the ONIX 3.0 standard (which is based on the ISO 3166-1 standard). If present, the given price is only relevant to transactions in the stated territories and can not be transacted at that price outside those regions. If empty, you may assume the price is good worldwide.

By default, the endpoint returns all prices in all currencies for each of the "basic" price types. Individual API keys can be configured to receive additional price types as determined by business need. If a client has any custom pricing, a price type of distributor-price will be returned as an additional price element. Additionally, if you are searching or require only a single currency, clients can specify a currency= parameter using a comma seperated list, which will only return the specified currencies. Note: Not all products and variants have prices in every price type or currency. If you specify a currency the endpoint returns all prices with the specified currencies for the products a client can distribute. If there are no prices in the currency specified you'll receive empty price information.

For example:

GET /v4/products?currency=usd,gbp,eur

Price Types

Price type Purpose Notes
digital-list-price This is the general price from the publisher to a distributor. Your company mar or may not add mark-up, depending on your business terms. Default price type. Always included.
publisher-list-price This is the price the publisher has set for the print product, which can be used for comparison purposes. e.g. "Digital price saves 20 percent over the publisher's list price for the print book." Default price type. Always included.
distributor-price This is a custom price given to your company by the publisher. If present, it supersedes the digital list price. Default price type. Always included.
agency-price This is a fixed price to consumer. VST has agency agreements with some publishers for our retail channels. Your company will not transact at this price. Hidden. VST and publishers only.
catalog-price The catalog price is regenerated weekly from the digital list price. It is designed to reduce intra-week pricing variations and to quantize when those changes happen. This price is designed for brick-and-mortar stores that have to manage physical shelf price tags. Ask to have this added to your catalog.
ia-agency-price This is a fixed price to student when an institution is purchasing for its inclusive-access program. Your company will not transact at this price. Hidden. VST and publishers only.
ia-store-price This is a to-student purchase price good only in VST-powered e-commerce stores for products delivered through inclusive-access programs. Hidden. VST only.
inclusive-access-price This is the price to bookstore for products delivered through inclusive-access programs. Typically, the bookstore marks up this price. Requires signing IA agreement with VST.
print-on-demand-price This is the price to purchases an on-demand copy of the digital resource. This purchase has to happen within the VST ecosystem, but may be useful for your company to track. Ask to have this added to your catalog.
publisher-unique-price

This is a "special" price that can have different meanings to different publishers. Your company will not transact at this price.

Hidden. VST and publishers only.
recommended-retail This is a to-consumer purchase price good only in VST-powered e-commerce stores. (This is the "store price" in Manage.) Hidden. VST and certain publishers only.

Deltas

Customers have the ability to request deltas to only return products that have been added, removed or updated since their last pull. Customers can include from and until query string parameters to specify deltas from a specific date/timestamp (i.e. 2017-01-04T22:02:36+00:00) or a specific start and stop date.

Date/timestamps can be specific down to the HH:MM:SS of the timestamp include specifying a timezone using ISO 8601 formats. If you only include a date (1-1-2016) it will default the HHMMSS to 12:00:00 UTC. Additionally not specifying a specific timezone offset will default everything to UTC.

For example:

If a customer wishes to request everything that has changed since the last time they pulled given the last request was made on 2017-01-04T22:02:36+00:00 the request would look as follows:

GET /v4/products?from=2017-01-04T22:02:36+00:00

If a customer wishes to request everything that has changed within a specific timeframe the request would look as follows:

GET /v4/products?from=2017-01-04T22:02:36+00:00&until=2017-01-05T22:02:36+00:00

This would return everything within the 24 hour window between January 4th and 5th.

Data Dictionary (key data)

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

Failure (example)

See full list of error codes and messages.

Was this article helpful?
2 out of 3 found this helpful

Comments

0 comments

Article is closed for comments.