POST v3/catalog - All

The Catalog API will retrieve a company's entire catalog. Companies can choose specific requests to filter results and also configure paging on how many records are returned per page. Basic delta abilities are also available via the Catalog API, using the <updated> element to only return products that have changed since the last time a client pulled the catalog. It does require that the client keep track of the last pull date to ensure the right date is entered and product changes are not missed. Other notes:

  • Using the <distributable> element of TRUE/FALSE will tell you if an item is available for "sale" (i.e. codes can be created or redeemed).
  • If distributable = false, the item has likely been removed from your distribution set. If you are storing catalog data in your database, this item should be removed from sale until distributable = true.

Supported Roles and Authentication Protocols

Type Supported Values
Authentication Protocols API Key
Valid for Roles System to System

API Request

HTTP Verbs and URLs

POST v3/catalog/sets
POST v3/catalog
POST v3/catalog/manual
  • */catalog/sets only pulls products which are part of a companies assigned distribution sets (national, custom,etc)
  • */catalog pulls everything that is assigned to the calling company both distribution set(s) and manual rights
  • */catalog/manual pulls only products that have been manually assigned to requesting company

Request Headers

X-VitalSource-API-Key: ABCDEFGHIJKLMNOP
  • Replace Alphabet characters with your API key.

Request Body

Request

<?xml version="1.0" encoding="UTF-8"?>
<catalog>
	<page>0</page>

	<per-page>1000</per-page>
	<created>ge 2014-01-01</created>
	<updated>ge 2014-10-01</updated>

	<condition type="identifier">ABCDEFGH</condition>
	<include-packages>true</include-packages>
</catalog>

Element Descriptions

Element Description Valid Values  Required
page Page number for the catalog request; default pagination is 100 per page. Depending on the number of records in your distribution set, you will call multiple pages of data. Paging starts at Page 0. integer  Yes
per-page Valid values between 100 and 1,000; recommendation is to pull 1,000 at a time.  integer: 100-1000  Yes
created

Available created and updated operators are gt (>), ge (>=), lt (<), le (<=). The default value for this is "inception" (gt 20000101).

Accepts any valid ISO8601 formatted date. Specify to return items based on a specific timestamp down to the hour, minute and second on a specific day. Default returns are in UTC unless specified. (YYYY-MM-DDTHH:MM:SS+00:00). Including only a date will default the timestamp to be midnight UTC.

string: ge 2016-11-28T21:19:08+00:00  No
updated

Available created and updated operators are gt (>), ge (>=), lt (<), le (<=). The default value for this is "inception" (gt 20000101). Use YYYYMMDD for proper returns.

Accepts any valid ISO8601 formatted date. Specify to return items based on a specific timestamp down to the hour, minute and second on a specific day. Default returns are in UTC unless specified. (YYYY-MM-DDTHH:MM:SS+00:00). Including only a date will default the timestamp to be midnight UTC.

string: ge 2016-11-28T21:19:08+00:00 No 
include-packages Optional parameter; use to return package details in the catalog response. If not included, default is "false." true/false No 
condition Used if you are searching for a specific product, this allows for a search via SKU, or ISBN. Only provide when looking for a specific title or set of titles. Available condition types are limited to "identifier" which will search all numeric values within the catalog. 90787223718272  No

Request Response

curl -X POST -H "User-Agent: ScottG" -H "Content-Type: text/xml" -H "X-VitalSource-API-Key: ABCDEFGHIJKLMNOP" -d '<?xml version=\"1.0\" encoding=\"UTF-8\"?>
<catalog>
<per-page>1000</per-page>
<created>ge 20140101</created>
<updated>ge 20141001</updated>
</catalog>' 'https://api.vitalsource.com/v3/catalog/'
HTTP Code: 200
<catalog items="17002" total-pages="171" page="0" per-page="100">
  <item>
    <sku>9780080548166</sku>
    <vbid>1259221652</vbid>
    <created>Thu, 21 Aug 2008 02:35:25 +0000</created>
    <updated>Tue, 21 Jan 2014 13:43:46 +0000</updated>
<off-sale-date>23 Sep 2017</off-sale-date> <type>Single</type> <downloadable-duration>180 Days</downloadable-duration>
 <online-duration>Perpetual</online-duration>
 <book-format>pbk</book-format> <kind>book</kind> <build-status>In Inventory</build-status> <url>http://vitalsource.com/search?term=9780080548166&duration=180</url> 
<description>The finding by Emil Fischer that glucose ...</description>
 <publication-date>09/2011</publication-date>
 <discount-code>091254</discount-code>
 <author>Hari Garg</author>
 <title>Carbohydrate Chemistry, Biology and Medical Applications</title>
 <sort-title>Carbohydrate Chemistry, Biology and Medical Applications</sort-title> 
 <edition>0</edition>
 <icon-url>http://covers.vitalbook.com/vbid/9780080548166/width/120</icon-url>
 <sampleable>false</sampleable> 
 <page-count>414</page-count>

<parent-isbn/> <copyright-date></copyright-date> <copyright-year></copyright-year>
 <distributable>true</distributable>
 <print-drm-text></print-drm-text> 
 <copy-drm-text></copy-drm-text> <subjects> <subject schema="bisac" code="BUS025000">Entrepreneurship</subject>
 <subject schema="coursesmart" code="cs.bus_ecn.mgmt.entre">Entrepreneurship</subject> </subjects> <pricelist> <publisher-list-price currency="USD">125.0</publisher-list-price> 
<agency-price currency="USD">125.0</agency-price> 
 <digital-list-price currency="USD">125.0</digital-list-price>
 <sell-price currency="USD">125.0</sell-price> </pricelist>
 <publisher> <publisher-name>Elsevier Science</publisher-name>
 <imprint-name>Elsevier Science</imprint-name> </publisher>
 <aliases> <eisbn-canonical>9780080558141</eisbn-canonical> <isbn-canonical>9780080548166</isbn-canonical>
 <print-isbn-canonical>9780080548166</print-isbn-canonical>
 <fpid></fpid>
 <fpid-equivalent></fpid-equivalent>
 <vbid-equivalent></vpid-equivalent>
 <isbn13>9780080548166</isbn13>
 <isbn10>0-08-054816-4</isbn10> <additional-isbns> <isbn type="saleable-print-isbn-10">12345667</isbn> <isbn type="saleable-print-isbn-13">123456787</isbn> </additional-isbns> </aliases>
 <owner> <company> <id>219</id> 
 <name>Elsevier S & T</name> </company> </owner> <distributor> <company> <id>326</id> <name>Fordham University Bookstore</name> </company> </distributor> </item> </catalog>
require 'uri'
require 'net/http'

url = URI("https://api.vitalsource.com/v3/catalog/")

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

request = Net::HTTP::Post.new(url)
request["user-agent"] = 'TEST AGENT'
request["content-type"] = 'text/xml'
request["x-vitalsource-api-key"] = 'ABCDEFGHIJKLMNOP'
request["cache-control"] = 'no-cache'
request.body = "<?xml version=\\\"1.0\\\" encoding=\\\"UTF-8\\\"?>\n<catalog>\n<per-page>1000</per-page>\n<created>ge 20140101</created>\n<updated>ge 20141001</updated>\n</catalog>"

response = http.request(request)
puts response.read_body
<?php

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

$body = new http\Message\Body;
$body->append('<?xml version=\\"1.0\\" encoding=\\"UTF-8\\"?>
<catalog>
<per-page>1000</per-page>
<created>ge 20140101</created>
<updated>ge 20141001</updated>
</catalog>');

$request->setRequestUrl('https://api.vitalsource.com/v3/catalog/');
$request->setRequestMethod('POST');
$request->setBody($body);

$request->setHeaders(array(
  'cache-control' => 'no-cache',
  'x-vitalsource-api-key' => 'ABCDEFGHIJKLMNOP',
  'content-type' => 'text/xml',
  'user-agent' => 'ScottG'
));

$client->enqueue($request)->send();
$response = $client->getResponse();

echo $response->getBody();
?php>
var client = new RestClient("https://api.vitalsource.com/v3/catalog/");
var request = new RestRequest(Method.POST);
request.AddHeader("cache-control", "no-cache");
request.AddHeader("x-vitalsource-api-key", "ABCDEFGHIJKLMNOP");
request.AddHeader("content-type", "text/xml");
request.AddHeader("user-agent", "Test User");
request.AddParameter("text/xml", "<?xml version=\\\"1.0\\\" encoding=\\\"UTF-8\\\"?>\n<catalog>\n<per-page>1000</per-page>\n<created>ge 20140101</created>\n<updated>ge 20141001</updated>\n</catalog>", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
var http = require("https");

var options = {
  "method": "POST",
  "hostname": "api.vitalsource.com",
  "port": null,
  "path": "/v3/catalog/",
  "headers": {
    "user-agent": "TEST USER",
    "content-type": "text/xml",
    "x-vitalsource-api-key": "ABCDEFGHIJKLMNOP",
    "cache-control": "no-cache",
  }
};

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.write("<?xml version=\\\"1.0\\\" encoding=\\\"UTF-8\\\"?>\n<catalog>\n<per-page>1000</per-page>\n<created>ge 20140101</created>\n<updated>ge 20141001</updated>\n</catalog>");
req.end();
import http.client

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

payload = "<?xml version=\\\"1.0\\\" encoding=\\\"UTF-8\\\"?>\n<catalog>\n<per-page>1000</per-page>\n<created>ge 20140101</created>\n<updated>ge 20141001</updated>\n</catalog>"

headers = {
    'user-agent': "TEST USER",
    'content-type': "text/xml",
    'x-vitalsource-api-key': "ABCDEFGHIJKLMNOP",
    'cache-control': "no-cache",
    }

conn.request("POST", "/v3/catalog/", payload, headers)

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

print(data.decode("utf-8"))
HttpResponse<String> response = Unirest.post("https://api.vitalsource.com/v3/catalog/")
  .header("user-agent", "TestUser")
  .header("content-type", "text/xml")
  .header("x-vitalsource-api-key", "ABCDEFGHIJKLMNOP")
  .body("<?xml version=\\\"1.0\\\" encoding=\\\"UTF-8\\\"?>\n<catalog>\n<per-page>1000</per-page>\n<created>ge 20140101</created>\n<updated>ge 20141001</updated>\n</catalog>") 
.asString();
 

Success

print(data.decode("utf-8"))

Element Descriptions

Element/field Description
items Returns the count of total items based on the request made
total-pages  Total number of pages available; when building an entire catalog, you will need to use this number to call the proper amount of pages to ingest your entire catalog.
page Current page
per-page Records being returned per page based on your initial request
item  Main element; will return multiple <item /> elements when retrieving an entire list, one for each item returned.
sku Unique product SKU; this will be used to make additional calls to create codes
created Date the product was created
updated Date the product was last updated
off-sale-date Date the product will be removed from distribution
type Rental, Single, Package, or Demo will be returned
downloadable-duration Duration of license options for the downloadable version of the book, all values are returned in days
online-duration Duration of license options for the online version of book, all values are returned in days
book-format Format of the book; dashML, pbk, pdf, ePub are valid returns. If book is available in multiple formats, it will return multiple elements for each as each has a unique SKU
kind The type of the asset/product including book, chapter, eresource, title
discount code The discount code returned from publishers, typically from an ONIX feed. Alpha numeric value
url Store URL for book
description Author/publisher description of book, returned as plain text
publication-date MM/YYYY of publication date
author Author name
title Book title
sort-title  
edition Asset edition
icon-url URL to thumbnail icon
sampleable Boolean value to identify whether the book is available for faculty sampling
page-count Number of pages in the book
copyright-date Full copyright date
copyright-year Copyright year
print-drm-text Display text for printing rules
copy-drm-text Display text for copying rules
subjects Element will return two sets of subject schemas, if available (bisac and coursemart)
parent-isbn For content types of chapters this will be populated tp group chapters back to titles
subject schema=biscac Returns both the BISAC code and the display text for the subject
subject schema=coursesmart Returns both the CouseSmart code and the display text for the subject
pricelist Element that displays the pricing details for the specific SKU/product
publisher-list-price  
agency-price  
digital-list-price  
sell-price  
publisher Returns publisher details
publisher-name Name of publisher 
imprint-name Imprint 
distributable Returns a true or false; this is used to determine if an item returned is available for sale within the caller's catalog. A false return means it has either been removed from distribution or there were problems with the build. If you are using deltas and wish to track what has been removed from your catalog, this element will change to false as items are removed from your distribution set.
aliases Element that returns the other ISBNs and identifiers related to the specific SKU/product
eisbn-canonical eISBN of product returned
isbn-canonical ISBN of product returned
print-isbn-canonical PrintISBN of product returned
additional-isbns An array of <isbn> elements that will return. These are ISBNs that relate to the product <item>. There can be 0 to many of these returned per product and should be used as a way to discover additional content.
fpid CourseSmartID of product returned if it exists (this can be empty)
fpid-equivalent Additional CourseSmart specific values for products where there is now a newer VitalSource equivalent
vpid-equivalent VitalSource specific equivalent where an older title was retired and now linked to a new title
isbn13 ISBN13 of product returned; will contain dashes
isbn10 ISBN10 of product returned; will contain dashes
owner Element that returns the owner of the product returned
company Element that displays the company information; if more than one company (child companies) owns the product, it will return each in separate company elements
id Company ID
name Company Name
distributor Element that returns the distributors of the product returned
company Element that displays the company information; if more than one company (child companies) has distribution rights to the product, it will return each in separate company elements.
id Company ID
name Company Name

Failure (example)

See full list of error codes and messages.

HTTP Code: 400
<?xml version="1.0" encoding="UTF-8"?> <error-response> <error-code></error-code> <error-text></error-text> </error-response>
Was this article helpful?
1 out of 2 found this helpful

Comments

0 comments

Article is closed for comments.