In almost all use cases this API has been replaced by the v4/products API. This endpoint is primarily for legacy customers. New integrations should use v4/products as their canonical source of catalog information.
The v3/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 this 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:
Verb/URI
https://api.vitalsource.com/v3/catalog
Data Definitions
|
Name
|
Usage
|
Description
|
Data Type
|
Example
|
Required
|
|---|---|---|---|---|---|
| URL param | Pulls everything that is assigned to the calling company both distribution set(s) and manual rights | N/A |
v3/catalog |
Yes | |
| sets | URL param | Pulls products which are part of a companies assigned distribution sets (national, custom, etc.) | string |
v3/sets |
No |
| manual | URL param | Pulls only products that have been manually assigned to requesting company | string |
v3/manual |
No |
| page | Message body | 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 |
123 |
No |
| per-page | Message body | Valid values between 100 and 1,000; recommendation is to pull 1,000 at a time. | integer |
150 |
No |
| created | Message body |
Available operators are gt (>), ge (>=), lt (<), le (<=). The default value for this is "inception" (gt 20000101). Accepts any valid ISO-8601 formatted date. Specify to return items based on a specific timestamp. Including only a date will default the timestamp to be midnight UTC. |
ISO-8601 |
ge 2010-07-01 |
No |
| updated | Message body |
Available operators are gt (>), ge (>=), lt (<), le (<=). The default value for this is "inception" (gt 20000101). Accepts any valid ISO-8601 formatted date. Specify to return items based on a specific timestamp. Including only a date will default the timestamp to be midnight UTC. |
ISO-8601 |
ge 2010-07-31 |
No |
| include-packages | Message body |
Adds package details to response body |
string |
true |
No |
| condition | Message body |
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. |
SKU |
<condition type="identifier"> VBID_OR_SKU</condition> |
Request Headers
X-VitalSource-API-Key: ALLCAPSANDNUMBERS
Request Body - default example
<?xml version="1.0" encoding="UTF-8"?> <catalog> <page>0</page> <per-page>1000</per-page> <created>ge 2000-01-01</created> <updated>ge 2000-01-01</updated> <include-packages>true</include-packages> </catalog>
Request Body - identifier example
<?xml version="1.0" encoding="UTF-8"?> <catalog> <page>0</page> <per-page>1000</per-page> <created>ge 2018-01-01</created> <updated>ge 2018-01-01</updated> <condition type="identifier">VBID_OR_SKU</condition> <include-packages>true</include-packages> </catalog>
Response
Response body - default (incomplete)
<catalog items="17002" total-pages="171" page="0" per-page="100"> <?xml version="1.0" encoding="UTF-8"?>
<catalog items="3" total-pages="1" page="0" per-page="1000" status="complete">
<item>
<sku>BOOKSHELF-TUTORIAL</sku>
<vbid>BOOKSHELF-TUTORIAL</vbid>
<created>Mon, 04 Aug 2014 13:37:55 +0000</created>
<updated>Fri, 19 Oct 2018 20:56:37 +0000</updated>
<off-sale-date/>
<type>Single</type>
<downloadable-duration>perpetual</downloadable-duration>
<online-duration>365 days</online-duration>
<book-format>ePub</book-format>
<build-status>In Inventory</build-status>
<url>https://www.vitalsource.com/textbooks?term=BOOKSHELFTUTORIAL</url>
<description/>
<publication-date/>
<author>VSM</author>
<title>Bookshelf Tutorial</title>
<sort-title>Bookshelf Tutorial</sort-title>
<edition>0</edition>
<icon-url>https://covers.vitalbook.com/vbid/BOOKSHELF-TUTORIAL/width/120</icon-url>
<sampleable>true</sampleable>
<page-count>0</page-count>
<copyright-date/>
<copyright-year/>
........
........
<aliases>
<eisbn-canonical/>
<isbn-canonical>BOOKSHELFTUTORIAL</isbn-canonical>
<print-isbn-canonical/>
<fpid/>
<isbn13/>
<isbn10/>
<additional-isbns>
<isbn type="e-isbn-10">0123456789</isbn>
</additional-isbns>
</aliases>
.......
.......
<pricelist>
<publisher-list-price>0.00</publisher-list-price>
<agency-price/>
<digital-list-price>0.00</digital-list-price>
<sell-price/>
</pricelist>
<publisher>
<publisher-name>VitalSource Technologies</publisher-name>
<imprint-name>VCS Internal & Sales</imprint-name>
</publisher>
.......
.......
</catalog>
Response Descriptions
|
Name
|
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(s) name |
| title | Asset 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 |
| pricelist | Element that displays the pricing details for the specific SKU/product |
| publisher-list-price | |
| agency-price | |
| digital-list-price | |
| sell-price | |
| publisher | Publisher details |
| publisher-name | Publisher name |
| imprint-name | Imprint name |
| 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. You cannot sell assets marked false. |
| aliases | Element that returns the other ISBNs and identifiers related to the specific SKU/product |
| eisbn-canonical | eISBN of the product |
| isbn-canonical | ISBN of the product |
| print-isbn-canonical | PrintISBN of product |
| 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) |
| 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 | VitalSource Manage company ID |
| name | VitalSource Manage company name |
| distributor | VitalSource Manage distributors of this asset |
|
build-status
|
Status of the asset in VitalSource Manage |
Error Codes
|
HTTP & Error messages
|
Message
|
Notes
|
|---|---|---|
| 200 |
|
Success. Errors provided simultaneously |
| 422 |
Bad parameters |
|
| 422 |
Bad page number |
|
| 422 |
Bad per-page number |
|
| 422 |
Bad date parameter |
|
| 992 |
API user company is misconfigured (has multiple companies) |
Comments
Article is closed for comments.