On Wednesday July 31, 2019, version 1.4.6 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.4.6 release notes

We are now exposing two new data elements as part of the Title representation: asin and customSubjectCategory. Both have also been added to the product display view which many people use.

/domains/PRH.US/titles/9780139615320

        "asin": "0139615326",
        "customSubjectCategory": "Occult Sciences",
        "otherFields": {

You can also use customSubjectCategory as a filter parameter.

/domains/PRH.US/titles?customSubjectCategory=Occult%20Sciences

{
  "status": "ok",
  "recordCount": 2,
  "startTimestamp": "2019-07-31T14:50:12Z",
  "endTimestamp": "2019-07-31T14:50:12Z",
  "timeTaken": 9,
  "data": {
    "titles": [
      {
        "isbn": 9780139615320,
        "isbnHyphenated": "978-0-13-961532-0",
        "title": "Wisdom of the Mystic Masters",
        "subtitle": null,
        "author": "Joseph J. Weed",
        "onsale": "1971-02-01",

Finally, we changed the name of one of the site filters used by the sales platform.

New Feature

• [RHAPI-1167] - Expose ISBNxASIN data

Task

• [RHAPI-1171] - Expose SUBJECTLONG as "customSubjectCategory"
• [RHAPI-1172] - Add "customSubjectCategory" filter parameter
• [RHAPI-1174] - Change PreK12 siteFilter to Elementary

On Wednesday July 3, 2019, version 1.4.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.4.5 release notes

This release fixes a couple bugs and adds a couple of new features. Last month we added a new isKids element in the search display results but it was not consistently being populated because of a SQL error. Similarly the ignoreCatUri was not generating the proper SQL request and both of those problems were resolved though there are still performance problems with the 'ignoreCatUri' parameter.

As for new features, we added a new element childrensBookCategory as part of the Title representation for the kids group. The data comes from the BOOK_CATG field in MyHouse.

We also added a description to the contributor representation in the work list display view, roleCodeDesc, which contains text such as "Author" or "Reader". This makes it easier to build logic against a specific role when consuming both US and UK data as the role codes are not consistent between the two systems but the descriptions are fairly close.

Finally, we added a new filter parameter hasAgeRange that can be used to restrict the results to just titles where AGERANGECODE is populated (hasAgeRange=true) or not (hasAgeRange=false). This feature was useful for filtering data out of the SALESPLATFORM domain as part of specifying siteFilter=Backlist.

Bug

• [RHAPI-1158] - Search display element isKids not consistently populated
• [RHAPI-1160] - The ignoreCatUri parameter does not test catSetId

New Feature

• [RHAPI-1159] - Expose BOOK_CATG element as part of Title representation
• [RHAPI-1156] - Add contrib role desc to works list display view
• [RHAPI-1166] - Add filter hasAgeRange

On Wednesday June 5, 2019, version 1.4.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.4.4 release notes

This release adds a few new features and fixes a bug that was throwing an error in the peeps view when some data was not available.

We enhanced the /search/views/search-display endpoint to include a count of roles for authors and the 'isKids' and 'isNumbered' flags for series

/domains/PRH.US/search/views/search-display?q=David%20Womersley

      {
        "id": "author-2060462-PRH.US",
        "key": "2060462",
        "name": "David Womersley",
        "docType": "author",
        "score": 2189.14,
        "seoFriendlyUrl": "\/authors\/2060462\/david-womersley",
        "authorId": "2060462",
        "authorOf": null,
        "photoCredit": null,
        "onTour": false,
        "authorBio": "David Womersley is the Thomas Warton Professor of Literature at the University of Oxford. Among his interests are Jonathan Swift (he was the general editor of the CUP edition of Swift), Daniel Defoe and Edward Gibbon, whose <i>Decline and Fall of the Roman Empire <\/i>he edited for Penguin Classics.",
        "hasAuthorPhoto": false,
        "firstInitial": "D",
        "lastInitial": "W",
        "authorPhotoUrl": "https:\/\/images.randomhouse.com\/author\/2060462",
        "roles": {
          "A": 1,
          "E": 8,
          "U": 2,
          "V": 7,
          "Z": 7
        }
      }

/domains/PRH.US/search/views/search-display?q=Horrible%20Harry

      {
        "id": "series-DPY-PRH.US",
        "key": "DPY",
        "name": "Horrible Harry",
        "docType": "series",
        "score": 1977.9231,
        "seoFriendlyUrl": "\/series\/DPY\/horrible-harry",
        "seriesAuthor": [
          {
            "authorId": 2138368,
            "authorDisplay": "Suzy Weaver Kline"
          }
        ],
        "seriesIsbn": "9780140385526",
        "seriesCount": 37,
        "seriesDescription": "For Horrible Harry, Song Lee, and the rest of their friends in Room 3B every day at school is a chance for fun, mystery, and adventure. And Harry is always at the center of it all!",
        "isNumbered": true,
        "isKids": true
      }

We also fixed an error so that you're now able to properly embed keywords in a Title response.

/domains/PRH.US/titles/9781635652901?zoom=https://api.penguinrandomhouse.com/title/titles/keywords/definition

    "_embeds": [
      {
        "keywords": [
          "gifts for dad;self-help books;motivational books;surfing books;biography;sports;biographies;self help;sport;spirituality;motivation;business books;autobiographies;self help books;creativity;happiness;sports books;sports biographies;books for dad;new age;surfing;belief;healing;biographies of famous people;spiritual books;inspirational books for women;self help books for women;self improvement books;intuition;autobiography;gratitude;surf;self care;self development books;affirmations;surf book;aura"
        ],
        "_embeds": null,
        "_links": [
          
        ]
      }
    ],

Bug

• [RHAPI-1154] - Error in getWorkViewPeeps

New Feature

• [RHAPI-1151] - Add role count to author objects in search-display view
• [RHAPI-1152] - Add isKids element to series objects in search-display view

Task

• [RHAPI-1098] - Add parameter to ListWorksRequest for selecting Simile version
• [RHAPI-1153] - Add zoom support for /internal

On Wednesday April 3, 2019, version 1.4.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.4.3 release notes

This release adds a new element to the Title representation called illustPhoto which is sourced from a pair of fields in the MyHouse database called ILLUSTPHOTO and ILLUSTPHOTO2.

/domains/PRH.US/titles/9781580934190

        "originalIsbn": null,
        "illustPhoto": "200 DUOTONE ILLUSTRATIONS AND 24 COLOR ILLUSTRATIONS",
        "otherFields": {
          
        },

This same element has also been added to the product display view, /domains/PRH.US/titles/9781580934190/views/product-display, so you can get this data on that summary as well.

The other change in this release has to do with the logic associated with the /keywords sub-resource, accessed from a particular ISBN. Previously we only exposed the keyword data that was associated with the exact ISBN that was specified as part of the request. So for example work ID #42 has two ISBNs, 9780834824492 and 9781590304587, but only 9780834824492 has an entry in the keywords table. So under version 1.4.2, this request for the keywords of 9781590304587 would return no data but it now returns the keywords from its sibling ISBN.

/domains/PRH.US/titles/9781590304587/keywords

    "keywords": [
      "judaism;jewish history;religious books;religion;jewish;prayer;parenting;spirituality;bible;faith;bible study;theology;devotional;spiritual;kabbalah;christian;christianity;ethics;philosophy;self help;work;family;reference;passover;islam;collection;psychology;catholic;occult;god;meditation;education;buddhism;job;relationships;prayers;spirit;how to;biography;marriage;picture books;inspiration;short stories;torah;hasidism;jewish culture;motherhood;wisdom;school;parenting books;meditations;love;art"
    ],

Task

• [RHAPI-339] - Add illustration count to Title representation
• [RHAPI-1114] - Add title_t.illustphoto and title_t.illustphoto2 values to titles data
• [RHAPI-1144] - Expose publisher keywords for any ISBN of the work
• [RHAPI-1147] - Add prhunited-source and prhunited-match views to /titles

On Wednesday March 6, 2019, version 1.4.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.4.2 release notes

This is a minor release that adds two features. For our special markets group, the siteFilter parameter now also accepts the value 'PreK12'.

For Canada, we've added the ability to filter out details in the /works/{workId}/views/product-display view with the parameter ignoreProductType. This parameter can be specified multiple times and will prevent the inclusion of any ISBNs in the formats element that have any of those product types.

Task

• [RHAPI-1139] - Create siteFilter for PreK-12 website
• [RHAPI-1140] - Add ignoreProductType parameter to product display view

On Monday February 4, 2019, version 1.4.1 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.4.1 release notes

In 2019 we will be starting to do monthly releases for the PRH API code. That means that as long as issues don't come out of testing during the second half of the month, a code update will go in some time shortly after the first of each month. This month we have a number of bug fixes along with a couple of enhancements.

Among the bugs that were addressed, we resolved an issue with the /works/{workId}/views/also-in/author endpoint where illustrators were being incorrectly considered. We also made a couple of fixes to the /works/views/sales-display view adjusting the SQL that was being generated to better match the requirements. Finally we fixed an issue where some missing data was causing some Australian queries to return a 500.

Flag and ignoreFlag filters

Two new features were added with this release. The first are two new filter parameters: flag and ignoreFlag. One of the elements in the Title representation is called flags and it can contain several different keywords indicating membership in different metadata groups. For example the 3PD flag indicates that an ISBN is owned by one of the third party distributions that PRH fulfills; the LIBRARY_BINDING flag indicates that this is a kids book with the heavy duty binding suitable for libraries. These keyword values can now be specified to either include (flag) or exclude (ignoreFlag) ISBNs with that quality from the result.

For example, this request will list the works that have at least one ISBN with a LIBRARY_BINDING.

/domains/PRH.US/works?flag=LIBRARY_BINDING

{
"status": "ok",
"recordCount": 2030,

While this will give us all of the "coming soon" titles excluding any 3PD.

/domains/PRH.US/titles?showComingSoon=true&ignoreFlag=3PD

{
"status": "ok",
"recordCount": 2339,

Addition of hasAudioEdition element to work list display

The endpoint /works/views/list-display has a new element called hasAudioEdition that indicates whether any of its child ISBNs has a format family of "Audio". Here is an example call:

/domains/PRH.US/works/views/list-display?workId=202476&workId=221591

{
  "status": "ok",
  "recordCount": 2,
  "startTimestamp": "2019-02-04T19:58:35Z",
  "endTimestamp": "2019-02-04T19:58:35Z",
  "timeTaken": 22,
  "data": {
    "works": [
      {
        "workId": 202476,
        "title": "Last Boat Out of Shanghai",
        ...
        "hasExcerpt": true,
        "hasAudioEdition": false,
        ...
      },
      {
        "workId": 221591,
        "title": "The Golden Tresses of the Dead",
        ...
        "hasExcerpt": true,
        "hasAudioEdition": true,

Bug

• [RHAPI-1127] - also in author view should only consider Author role
• [RHAPI-1130] - isbnSort=higherEducation is not working anymore
• [RHAPI-1131] - AU author display view generating JBoss error
• [RHAPI-1134] - Retail - sales-display call is returning record count but no actual data for catUri=childrens (S1)
• [RHAPI-1135] - Higher Education sales-display - Record count and number of results returned not in sync

Task

• [RHAPI-1125] - Add flags and ignoreFlags filter parameters
• [RHAPI-1129] - Add hasAudioEdition flag to /works/views/list-display
• [RHAPI-1132] - Testing v1.4.1 (February 2019)
• [RHAPI-1137] - Deploy to DEV sometimes fails

On Thursday December 6, 2018, version 1.3.24 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.3.24 release notes

The most significant change in this release is around the behavior of the parameters workOnSaleFrom and workOnSaleTo. When we changed how work attributes are derived, we changed how we define the on-sale date that is associated with a work using the date of its frontlisiest (or representative) ISBN rather than the earliest on-sale of any of its ISBNs. At that time of that change, we left the behavior of the parameters workOnSaleFrom and workOnSaleTo as they were, testing against the earliest on-sale date of a work rather than the frontlistiest. But that policy did not make sense given the names of those parameters and so with this release, we are aligning the parameters to test against the on-sale date of the representative ISBN of the work rather than the earliest on-sale date. To enable people to continue to use the functionality of being able to test against the earliest on-sale date (such as in cases where it is being used to identify works that have been newly released), we have added two new parameters workFirstOnSaleFrom and workFirstOnSaleTo which can be used instead.

Also in this release, we've added a new endpoint for internal clients only that exposes sales assets. The endpoint can be accessed as /titles/{isbn}/sales-assets and returns data from the MYH_SA table in MyHouse.

/domains/PRH.US/titles/9781601425621/sales-assets

    "salesAssets": [
      {
        "fileId": 13,
        "ean": 9781601425621,
        "assetCode": "COVERIMAGE",
        "assetSeq": 0,
        "fileName": null,
        "fileNameOrig": "9781601425621.jpg",
        "fileNote": null,
        "family": false,
        "dropin": false,
        "mti": false,
        "saleskit": true,
        "ecatalog": true,
        "watermark": true,
        "boxFile": {
          "fileId": "10469712563",
          "folderId": null,
          "etag": "2",
          "size": "1129891",
          "sha1": "d359af6f1691425f638c3635af708468da8e7ae9",
          "downloadUrl": "https:\/\/randomhouse.box.com\/shared\/static\/lc71yabh08s5klne4uye.jpg",
          "_embeds": null,
          "_links": [
            
          ]
        },
        "_embeds": null,
        "_links": [
          
        ]
      }
    ],

We also resolved a couple of bugs, one where we were displaying too few events in the /events endpoint and another where the representative element in the /works/views/list-display endpoint was not always correct if the preferLanguage parameter was specified.

Bug

• [RHAPI-1111] - Rename EAN element to ISBN in PEEPS view
• [RHAPI-1116] - Author events missing from /events
• [RHAPI-1117] - onSaleTo parameter returns works with on sale dates farther in future.
• [RHAPI-1122] - Representative ISBN not correct when preferLanguage supplied

Task

• [RHAPI-1088] - Create internal endpoint for sales assets

Back on August 1, 2018, we announced a change to how work attributes are derived. One of these changes was to the on-sale date that is associated with a work using the date of the most representative ("frontlistiest") ISBN rather than the earliest. However we preserved the earliest on-sale date in a column we call FIRST_ONSALEDATE and so going forward, works have two dates associated with them

• onsaledate : the on-sale date of the representative ISBN (often the most recent)
• first_onsaledate : the on-sale date of the earliest ISBN that is part of this work (always the oldest)

To maintain backward compatability, we migrated the filter parameters workOnSaleFrom and workOnSaleTo to test against the "first_onsaledate" field however this does not suit the names of those parameters. Therefore in the next release of the API, this will be changing to instead operate against the "onsaledate" (most recent) field. To preserve the existing functionality, you will need to access the new parameters workFirstOnSaleFrom and workFirstOnSaleTo.

On Tuesday November 6, 2018, version 1.3.23 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.3.23 release notes

PEEPS view updated

We worked with the PEEPS project to update the data elements that we return from the /works/views/peeps endpoint.

Internal endpoint added

We added an subresource to the details of an ISBN that returns a number of data points that are useful to internal applications. Because some of this data is considered sensitive, users who try to access this data via the public endpoints will get back an HTTP 401 Unauthorized. It can be specified by appending /internal to the end of a title specification.

/domains/PRH.US/titles/9780141372426/internal

The representation includes data such as the SAP network number and span code as well as people such as the editor and publicist.

Abstract primary contributors

The changes with RHAPI-1070 and RHAPI-1036 pertain to removing hard coded values referring to specific contributor roles that were specific to the US and Canada. As we expand to include UK and Australian data, we needed to identify authors and illustrators via table entries rather than with these hard coded values.

Author has link only when photo is present

As part of the Author representation, we had previously always returned a _links object with rel=icon because it could be constructed from the AUTHORID value and a static prefix. However we've now added logic such that this link is only included if our database indicates that such an image is present. It should be fairly trivial to construct what the URLs would be for these authors where the database does not report the image present and it is helpful to some sites to know in advance whether they can expect to find an image.

Other changes

There were several other changes including one for PRH.com which adds an ID field to the keyword documents returned by search and another which added a parameter for Sales Platform that has to do with selecting representative ISBNs. In addition, a bug was fixed where a /titles request for a series without a category would not return data when it should.

Bug

• [RHAPI-1070] - also-in author view has hard-coded contrib role codes
• [RHAPI-1073] - /titles zoom request for Series includes INNER JOIN to ISBNxCATEGORY

Task

• [RHAPI-658] - Publicist Information on RHAPI
• [RHAPI-1027] - Add Title data attributes (internal endpoint)
• [RHAPI-1036] - Change how author-display and search-display identify primary contributors
• [RHAPI-1059] - Add id value to keyword docType in Search and Predictive Search
• [RHAPI-1063] - Add Solr endpoint to /healthy
• [RHAPI-1071] - Create a parameter that will drive a specific format priority logic for Higher Education
• [RHAPI-1072] - Modify Author "icon" link when cover image is present
• [RHAPI-1074] - Update PEEPS view