On Wednesday June 8, 2016, version 1.2.5 of the Enhanced PRH API was released to production. If you encounter any problems with your applications as a result of these changes, please contact us at api@penguinrandomhouse.com.

Version 1.2.5 release notes

Several fields were added to the /works/{workId}/product-display view to support the sales websites. The "format" element got "subname" added; the "contributors" element got "photoCredit" and "photoDate"; and a new element "dimensions" was added with properties "length", "width", "depth", and "grossWeight".

/domains/PRH.US/works/391486/views/product-display

          "format": {
            "code": "MM",
            "name": "Mass Market Paperback",
            "subcode": "PR",
            "subname": "Premium Mass Market",
            "family": "Paperback"
          },

          "contributors": {
            "010-1001": {
              "id": 9834,
              "display": "Pauline Gedge",
              "roleCode": "A",
              "roleName": "Written by",
              "ontour": false,
              "spotlight": "PAULINE GEDGE is the award-winning and bestselling author of thirteen previous novels, ten of which are inspired by Egyptian history. Her first,&#160;<i>Child of the Morning<\/i>, won the Alberta Search-for-a-New-Novelist Competition. In France, her second novel,&#160;<i>The Eagle and the Raven<\/i>, received the Jean Boujassy award from the Soci&eacute;t&eacute; des Gens des Lettres, and&#160;<i>The Twelfth Transforming<\/i>, the second of her Egyptian novels, won the Writers Guild of Alberta Best Novel of the Year Award. Her books have sold more than 250,000 copies in Canada alone; worldwide, they have sold more than six million copies and have been translated into eighteen languages. Pauline Gedge lives in Alberta.",
              "seoFriendlyUrl": "\/authors\/9834\/pauline-gedge",
              "attr": 1001,
              "firstInitial": "P",
              "lastInitial": "G",
              "hasAuthorPhoto": true,
              "photoCredit": null,
              "photoDate": null,
              "authorPhotoUrl": "https:\/\/images.randomhouse.com\/author\/9834"
            }
          },

          "dimensions": {
            "length": "7.470",
            "width": "4.240",
            "depth": "1.230",
            "grossWeight": "13.440"
          },

We also fixed a bug in the same view where the "awardYear" element was being returned with a zero instead of a NULL.

/domains/SALESINTERNATIONAL/titles/9780385751063/views/product-display

        {
          "ean": "9780385751063",
          "description": "IRA Young Adult Choices",
          "level": "WINNER",
          "date": null,
          "awardYear": null
        },

Bug

• [RHAPI-501] - &rows=0 not working in author display
• [RHAPI-523] - &rows=0 not working in search-display
• [RHAPI-526] - NPE in listSearchWorks line 63

New Feature

• [RHAPI-493] - Add book full dimensions and weight to product-display
• [RHAPI-517] - Add preferExport logic to search-display view

Task

• [RHAPI-514] - Add author image photo credit into product-display
• [RHAPI-516] - Add sub-format name to product-display
• [RHAPI-522] - Is it possible to return 'null' instead of '0' when the awardYear field is not populated

On Friday May 20, 2016, version 1.2.4 of the Enhanced PRH API was released to production. If you encounter any problems with your applications as a result of these changes, please contact us at api@penguinrandomhouse.com.

Version 1.2.4 release notes

This fix was rushed into PRD to resolve an issue where works without covers were not being returned correctly by the product display view.

In addition some more new fields have been added to the product display output including canPrice and authorPhotoUrl. Two other code/description objects were added as well, grade and salesRestriction.

A new computed flag was added to the Title representation named 'MOVIE_TIE_IN' that is set whenever the TITLE.MTI field is 'Y' or TITLE.VERS is 'Movie Tie-In Edition'.

Two new filters were added, showMovieTieIn which restricts (or excludes) based on the that 'MOVIE_TIE_IN' flag and showExportOnly which does the same on the 'EXPORT' flag.

Finally, we worked with Mashery to better understand the configuration so that we could properly not cache certain requests. Any POST requests to the /titles or /works endpoint that needed to supply a large number of parameters are no longer cached. Also any request that includes "?sort=random" is not cached so that you can do this:

/domains/PRH.US/works?sort=random&rows=1

      "works":[
         {
            "workId":​302594,
            "title":"The Song of the Cid",
            "author":"Anonymous",
            "onsale":"2009-03-31",
            "language":"SP",

And then make the same request immediately and get a different result

      "works":[
         {
            "workId":​350665,
            "title":"Trading in the Zone",
            "author":"Mark Douglas",
            "onsale":"2001-01-01",
            "language":"E",

Bug

• [RHAPI-222] - sort=random doesn't work with Mashery caching
• [RHAPI-505] - Don't cache POST requests

New Feature

• [RHAPI-508] - Create a filter on export editions

Task

• [RHAPI-487] - Create a "Movie tie-in" flag
• [RHAPI-492] - Add Canadian price to product-display
• [RHAPI-494] - Add grade range description to product-display
• [RHAPI-504] - Add author image link into product-display

Sub-task

• [RHAPI-495] - Add salesRestriction (overhead field) to product-display

Up until now, the only version of the Enhanced PRH API that has been exposed to the public is the current production version. The version that is under development on our internal test servers has only been available to folks within the company who have access to that direct endpoint. As we collaborate with different partners to enhance the API and deliver new features, the lack of access to a development build can hamper evaluation of these changes and delay integration work. It also means that we cannot ask our partners to help us regression test and confirm that the latest candidate build works for their purposes.

TST version of the API

I am pleased to announce that we are now able to grant access to internal TST version of the Enhanced PRH API. Once access has been granted, you need only change the host name from api.penguinrandomhouse.com to api-test.penguinrandomhouse.com and use the related test key to access the latest development release. All other aspects of the request (i.e. path, parameters) will remain the same. I've tested this myself with an internal application that uses configuration to drive the host name, using api-test for the development build of the app and api for the production build, and swapping out the keys.

Requesting access

The package that contains this access does not allow for self registration; access to the TST version of the API is granted on a case-by-case basis. If you require access to the development build, please send an e-mail to api@penguinrandomhouse.com.

Chris Gilbert
API Developer
Penguin Random House

On Friday May 13, 2016, version 1.2.3 of the Enhanced PRH API was released to production. If you encounter any problems with your applications as a result of these changes, please contact us at api@penguinrandomhouse.com.

Version 1.2.3 release notes

This release fixes a bug where the Work representation's cover URL always used the frontlistiest ISBN but now choose the first  ISBN in frontlistiest order that has a cover.

The Sales platform web project requested several fields to be added to existing endpoints. The product-display view now includes both salesRestrictions and isbnHyphenated. The /title/{isbn}/content endpoint now contains two blurbs from the TI sheets, keynote and positioning. The author-display view includes the field consumerFormat.

The Title Narrative Tool project modified their ant views to include a list of divisions.

The Children's group requested the ability to restrict both search and restrictive search with the division facet. It was already available on /search for 'work' and 'isbn' documents but was not previously available to restrict 'author' and 'series' documents. It was also not previously available on the /search/predictive endpoint.

Finally, PRH.com requested a couple of new views that return data in the work's list-display representation. The views use the recently added CO_PURCHASE table to generate a list of works that are related to the specified item based on the entries in this table. The view can be accessed three different ways: as /authors/{authorId}/views/also-purchased, /titles/{isbn}/views/also-purchased or /works/{workId}/views/also-purchased. There is also a new view that uses entries in the CATEGORY table in the 'LT' category set (Library Thing) to come up with a list of related works. This can be specified as /titles/{isbn}/views/matches-on-tag.

You can now also specify 'price' as a valid sort option. If you do, you must also specify either 'USD' or 'CAD' for the new parameter sortPriceTypeCode.

Bug

• [RHAPI-475] - Work cover image link may be to a non-existant cover

New Feature

• [RHAPI-444] - Add sales restrictions full rights to API
• [RHAPI-461] - Filter predictive search by Division
• [RHAPI-471] - Search for author and series documents with division facet
• [RHAPI-479] - Implement a sort parameter by price
• [RHAPI-484] - Create "also-purchased" works list view
• [RHAPI-485] - Create "matches-on-tag" works list view
• [RHAPI-486] - Add "subSeries" filter parameter

Task

• [RHAPI-473] - Add to the API the positioning statement and the short description from the TI sheet
• [RHAPI-483] - Add "divisions" to ant views
• [RHAPI-488] - Add title consumerFormat to author-display
• [RHAPI-491] - Add isbnHyphenated to product-display

On Tuesday May 3, 2016, version 1.2.2 of the Enhanced PRH API was released to production. If you encounter any problems with your applications as a result of these changes, please contact us at api@penguinrandomhouse.com.

Version 1.2.2 release notes

A bug fix for PRH.com was made regarding the series count on the author display view and some new features were added for the Author Alerts e-mail program.

The Work list display view got two new fields added to the representation, hasExcerpt and subtitle.

Several filter parameters were added: salesRestriction, saleStatus, subFormat, ignoreSubFormat, ignoreProductLine, ignoreProductType, showNoTitleBlock, workOnSaleFrom and workOnSaleTo. All of these parameters can be supplied for any list request (e.g. /works, /authors, /events). All but the last two are simply filters on columns of the TITLE table though the boolean test "showNoTitleBlock" is actually a test for a not null condition on the element returned as "titleBlock". The two date range parameters workOnSaleFrom and workOnSaleTo were added to allow requests to distinguish between filtering on the TITLE.ONSALEDATE (which is what the current onSaleFrom and onSaleTo do) to requests that would prefer to test WORK.ONSALEDATE.

In addition the awkwardly (and inconsistently) named parameter "hideBooksWithNoCover" has been deprecated and replaced with the better "showCovers". The old parameter has not been removed and will continue to work but going forward the IO Docs will show the better parameter name to encourage its use.

Bug

• [RHAPI-464] - Inconsistent series counts between author and series views?

New Feature

• [RHAPI-466] - Add filter parameters to support Author Alerts program
• [RHAPI-467] - Add fields to work list display to support Author Alerts program

Version 1.2.1 release notes

Previously version 1.2.1 was released as a hot fix. Since no announcement was made of that fix, I'll include the JIRA tickets for reference here.

Bug

• [RHAPI-462] - listTitles with ISBNs supplied does not correctly order results when rows=0
• [RHAPI-465] - listTitles with ISBNs supplied does not honor a sort specification

On Monday April 25, 2016, version 1.2.0 of the Enhanced PRH API was released to production. If you encounter any problems with your applications as a result of these changes, please contact us at api@penguinrandomhouse.com.

Version 1.2.0 release notes

In terms of changes visible to the public, this is a minor release with a single bug fix and a couple new fields added. The bug fix concerned the recently added canPrice field which was not being populated correctly. The Title representation got the salesRestriction field added containing an object that holds a code/description pair. Also the author display view got a new field titleOnsale which contains the on-sale date of the selected frontlistiest ISBN which may be different from the onsale field which contains the on-sale date of the Work.

Behind the scenes some changes were made that should help allow for a stricter management of version changes to the representations. Expect a documentation concept page on this subject in the near future.

Bug

• [RHAPI-457] - Canadian price not populated in author-display

Task

• [RHAPI-434] - Add Sales Restriction field to API
• [RHAPI-459] - Add TITLE.ONSALEDATE to author-display
• [RHAPI-460] - Connect to API UK datasource

On Thursday April 14, 2016, version 1.1.19 of the Enhanced PRH API was released to production. If you encounter any problems with your applications as a result of these changes, please contact us at api@penguinrandomhouse.com.

Version 1.1.19 release notes

This version saw several additions to the output and one new parameter added to the author display view. In addition one bug was fixed where under certain circumstances, work listings could display duplicate records.

The Title representation received two new fields, salesRestriction and isbnBlok,  values for which come straight from our internal systems. In addition we added a new derived flag in the flags element called "EXPORT" which is set whenever isbnBlok='EXPT' and is used to indicate an export-only edition.

/domains/SALESINTERNATIONAL/titles/9781601429278

            "flags":[
               "EXPORT"
            ],
            ...
            "titleBlock":"EXPT",

The Event representation had a new field added to the output.

/domains/PRH.US/events/1705290

            "referenceUrl":"www.bn.com",

The author display view was modified to include several new fields in the output.

/domains/SALESINTERNATIONAL/authors/29660/views/author-display

            "formatCode":"HC",
            ...
            "canPrice":null,
            ...
            "ageRange":null,
            "salesRestriction":null,
            "salesRestrictionCode":"07",
            ...
            "flags":[
               "INSIGHT"
            ],

In addition, a new parameter was added to the author display view, "preferExport". This parameter allows the international sales sites to display the correct cover without having to modify the existing frontlistiest logic. This boolean parameter can be set to true to control which ISBN is chosen for each of the works listed in the works array.

For example, let's look at work #252887 in the "SALESINTERNATIONAL" domain. It has two titles, one with the "EXPORT" flag and one without. The export edition has a frontlistiest sequence of 2 and so would normally not be selected as the ISBN for the author display works array.

/domains/SALESINTERNATIONAL/works/252887/titles?sort=frontlistiest

      "titles":[
         {
            "isbn":​9781601428165,
            "isbnHyphenated":"978-1-60142-816-5",
            "title":"Be Light",
            ...
            "flags":[
               "INSIGHT"
            ],
            "workId":​252887,
            "frontlistiestSeq":​1,
            ...
         },
         {
            "isbn":​9781601429278,
            "isbnHyphenated":"978-1-60142-927-8",
            "title":"Be Light",
            ...
            "flags":[
               "EXPORT"
            ],
            "workId":​252887,
            "frontlistiestSeq":​2,

Without preferExport set, the author display view selects the frontlistiest ISBN for each work returned.

/domains/SALESINTERNATIONAL/authors/244262/views/author-display

      "works":[
         {
            "id":​252887,
            "name":"Be Light",
            "isbn":​9781601428165,

However if preferExport is set to 'true', then ISBNs with the "EXPORT" flag will be preferred. Notice how the request below returns the ISBN ending in 9278 which had a frontlistiest sequence of 2.

/domains/SALESINTERNATIONAL/authors/244262/views/author-display?preferExport=true

      "works":[
         {
            "id":​252887,
            "name":"Be Light",
            "isbn":​9781601429278,

Bug

• [RHAPI-450] - work listing not returning distinct records

New Feature

• [RHAPI-431] - Add ISBN_BLOK to API

Task

• [RHAPI-434] - Add Sales Restriction field to API
• [RHAPI-435] - Add title block field to API title representation
• [RHAPI-437] - Add parameter to author display view to make works listing prefer export only edition
• [RHAPI-439] - Add REFERENCE_URL column to AUTHOREVENTS
• [RHAPI-445] - Add additional fields into views/author-display

On Wednesday March 23, 2016, version 1.1.18 of the Enhanced PRH API was released to production. If you encounter any problems with your applications as a result of these changes, please contact us at api@penguinrandomhouse.com.

Version 1.1.18 release notes

This is a minor release with one bug fix and one enhancement. The bug fix related to the subjects element in the List Titles resource where the second description was always a code. The enhancement was the addition of a 'hasAuthorPhoto' element to the contributors element in the Product Display view.

Bug

• [RHAPI-430] - listTitles - 2nd "subjects" description returns code

New Feature

• [RHAPI-419] - Add flag to indicate if author has a photo to work product display view

On Thursday February 18, 2016, version 1.1.17 of the Enhanced PRH API was released to production. If you encounter any problems with your applications as a result of these changes, please contact us at api@penguinrandomhouse.com.

Version 1.1.17 release notes

New fields

The work product display got two new elements added  to its representation: the "copyright" field that relates to the text excerpt and the "hasAuthorPhoto" field that (as you might guess) tells you whether an author photo exists.

New parameters

List endpoints can now take three new parameters related to age ranges: "ageRange", "ageRangeMin", "ageRangeMax". The "ageRange" field takes a list of values and expects strings like those that are found in SAP which are 4 characters long and are a concatenation of a two digit lower bound and two digit upper bound such as '0005' or '0408'. This parameter can be used to test for specific age range values such as books tagged as appropriate for ages 4 to 8 ('0408') but not any others. The "ageRangeMin" and "ageRangeMax" take single integer values and can be used to do a mathematical comparison without enumerating all the different age range pairs. For example if you set "ageRangeMin" to '4', then you would get back titles tagged with the '0408' age range and also the '0005' age range as well as any others where the max of the range indicated is greater than or equal to 4.

Predictive search changes

We have done some work behind the scenes to improve the quality of the predictive search results. The biggest improvement is around searching when the entry is a complete token (e.g. 'Janet') instead of just a partial (e.g. 'Ja'). In general, these results should now be much closer to the results you would get when you do a "regular" search.

Bug

• [RHAPI-326] - Predictive search returning different score for 'janet'
• [RHAPI-405] - listEvents bad SQL error
• [RHAPI-407] - /divisions returns duplicates
• [RHAPI-411] - eBooksOriginal + series.minPrintScore = 0 problem?

New Feature

• [RHAPI-408] - Add ISBNxMAIN.COPYRIGHT field to product display view
• [RHAPI-409] - Adding hasAuthorPhoto to /works/ID/views/product-display
• [RHAPI-413] - Add "ageRange", "ageRangeMin" and "ageRangeMax" parameters
• [RHAPI-422] - Add catUri and divisionCode parameters to getWorkViewAlsoInSeries