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.

Verb/URI

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

Data Definitions

Name
Usage
Description
Data Type
Example
Required
  URL param The default request N/A

v4/products

Yes 
page URL param 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. integer 

v4/products?page=1

No
per_page URL param Valid values between 1 and 1,000; recommendation is to pull 1,000 at a time. integer

v4/products?per_page=1000

No
from URL param ISO-8601 date/time ISO 

v4/products?from=2019-07-01T00:00:00Z

No
until URL param  ISO-8601 date/time ISO 

v4/products?until=2020-12-31T00:00:00Z

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

v4/products?include_details=subjects,metadata

No
currency URL param Supported ISO-4217 three letter currency code(s) separated by commas ISO

v4/products?currency=USD,WON,JPY,NZD

No 

 

Request Headers

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

Response Header - from example

This request would return all catalog items since 1-Jul-2019

GET https://api.vitalsource.com/v4/products?/v4/products?from=2019-07-01T00:00:00Z

Response Header - from & until example

This request would return all catalog items between 1-Jul-2019 and the end of 2020

GET https://api.vitalsource.com/v4/products?from=2019-07-01T00:00:00Z&until=2020-12-31T00:00:00Z

Response Header - include_details example

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

Response Header - currency example

GET https://api.vitalsource.com/v4/products?currency=USD,WON,JPY,NZD

Response

Response Body - default

{
"num_items": 867204,
"page": 123,
"per_page": 1000,
"total_pages": 868,
"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": []
},...

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. -1 provides unlimited coping and pasting. Values of 0 and 1 are not allowed. Otherwise the value should be 2 or greater.
copy_restrictions Display text for copying rules. -1 provides unlimited coping and pasting. Values of 0 and 1 are not allowed. Otherwise the value should be 2 or greater.
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:

 

Response Descriptions - prices

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

Name
Description
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 VitalSource or your direct agreements with publishers. Please work with your assigned customer success manager
value Price in decimal format
currency Supported ISO-4217 currency code 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. 

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.

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

 

Response Descriptions - price types

Name
Description
digital-list-price This is the general price from the publisher to a distributor. Your company may or may not add mark-up, depending on your business terms.
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."
distributor-price This is a custom price given to your company by the publisher. If present, it supersedes the digital list price.
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. Note: visible to 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. Note: Available upon request
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. Note: visible to publishers only
inclusive-access-price This is the price to bookstore for products delivered through inclusive-access programs. Typically, the bookstore marks up this price. Note: Requires signing IA agreement
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 VitalSource ecosystem, but may be useful for your company to track. Note: Available upon request
publisher-unique-price This is a "special" price that can have different meanings to different publishers. Your company will not transact at this price. Note: visible to 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.) Note: visible to publishers only

 

 

Error Codes

HTTP & Error messages 
Message
Notes
200

OK

 
400

Not Found

 
500

Internal Server Error

 

 

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

Comments

0 comments

Article is closed for comments.