On Thursday November 19, 2015, version 1.1.13 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.13 release notes

This is another minor release with a couple small fixes and additions. Some adjustments were made to the just added ANT views and we added the ability to embed award results in a Title request.

Of note is the filter parameter "showReadingGuides" which had previously been disabled due to poor performance but which had not provided any feedback that it was not working. For the moment, requests that include the "showReadingGuides" parameter will produce an HTTP 500 error. We have a pending database change where a flag is being computed to indicate the existence of reading guides and as soon as that is available, then this filter will be functional.

Bug

• [RHAPI-221] - listWorks with showReadingGuides=true times out
• [RHAPI-382] - showReadingGuides on listWorks doesn't work correctly

New Feature

• [RHAPI-385] - Add ability to embed award data with title requests

Task

• [RHAPI-378] - Remove "roleNoun" from ANT views
• [RHAPI-379] - Populate ANT view genre from first CN category
• [RHAPI-384] - Add check of TITLE_CONSUMER record count to /healthy

Sub-task

• [RHAPI-380] - Modify Title representation to pull pricing data from ISBNxPRICE

BISAC subject codes are a standard maintained by BISG and used throughout the publishing to identify the subject matter of books. At Penguin Random House, our publishers assign up to three BISAC codes to every ISBN. We've always exposed BISAC data in the API but we've recently improved and enhanced the handling of BISAC categories to give clients more flexibility in how they are used.

BISAC in the original API

In the original API, there was no /category resource and so the only access one had to categories was through the BISAC codes that were attributes of a Title record in fields such as SUBJECTCATEGORY1 which contained the BISAC code and SUBJECTCATEGORY1DESCRIPTION which not surprisingly contained the description. You could also filter title results by BISAC category but you could not list the categories themselves.

BISAC in the Enhanced PRH API

In the Enhanced PRH API, we've exposed more of the categorization system (see documentation of the Category resource) which not only for a Title to be associated with multiple categories but also for those categories to be part of multiple category sets, each of which can have its own hierarchy. For more information on categories in the Enhanced PRH API, see the Categories Concepts documentation page.

BISAC codes of a title

Under the Enhanced PRH API, the TITLE table still has up to three BISAC codes associated with it and that data is still available as an attribute of the Title representation however now it is represented in an array.

/domains/PRH.US/titles/9780140056433

subjects":[
   {
      "code":"FIC010000",
      "description":"Fiction - Fairy Tales, Folk Tales, Legends & Mythology"
   },
   {
      "code":"OCC000000",
      "description":"OCC000000"
   }
]

For folks that just need to know what BISAC codes can consume this much the same way that they would have in the original API.

Listing BISAC categories

You can use the /category endpoint to list BISAC categories by adding the "catSetId=BI" to the request.

/domains/PRH.US/categories?catSetId=BI&suppressLinks=true

      "categories":[
         {
            "catId":​3000000001,
            "description":"Antiques & Collectibles",
            "catUri":"ANT000000",
            "menuText":"ANT000000",
            "hasChildren":true,
            "seq":null,
            "_embeds":null,
            "_links":[

            ]
         },
         {
            "catId":​3000000002,
            "description":"Antiques & Collectibles - Americana",
            "catUri":"ANT001000",
            "menuText":"ANT001000",
            "hasChildren":false,
            "seq":null,
            "_embeds":null,
            "_links":[

            ]
         },

This is the standard representation for Category results. The catId is a PRH-generated, auto-assigned number that uniquely identifies this category among all PRH categories. The actual BISAC code itself is actually available in the catUri element. This is the analog of SUBJECTCATEGORY1 from the original API or subjects.code in the Title representation above. Similarly the SUBJECTCATEGORY1DESCRIPTION (or subjects.description) is available in the description element.

For the menuText element, which for CN categories is a short version of the description, we chose to populate it with the BISAC code since we didn't have an alternative description. I would not recommend using it be if we ever got access to an abbreviated BISAC description, this is where it would be returned.

You can see that for "ANT000000" the hasChildren element is true while for "ANT001000" it is false giving you information about where these categories fall within the hierarchy.

Finally the seq element is only populated when a specific Title or Work is identified (e.g. /works/258951/categories) and _embeds and _links are used for the zoom/embed pattern.

Searching by BISAC code

As you can see in the previous section, the catId is *not* the BISAC code. So while you certainly may filter results using a BISAC category's catId, it would require looking up the value first.

/domains/PRH.US/categories?catUri=ANT001000

         {
            "catId":​3000000002,
            "description":"Antiques & Collectibles - Americana",
            "catUri":"ANT001000",
            "menuText":"ANT001000",
            "hasChildren":false,
            "seq":null,
            "_embeds":null,
            "_links":[

            ]
         }

But since you can search by catUri, there's no need to first look up the catId unless you want to.

/domains/PRH.US/works?catUri=ANT001000

{
   "status":"ok",
   "recordCount":​10,
   "startTimestamp":"2015-11-13T11:12Z",
   "endTimestamp":"2015-11-13T11:12Z",
   "timeTaken":​5,
   "data":{
      "works":[
         {
            "workId":​197022,
            "title":"Long May She Wave",
            "author":"Kit Hinrichs",
            "onsale":"2013-06-11",
            "language":"E",
            "seoFriendlyUrl":"/books/197022/long-may-she-wave-by-kit-hinrichs",
            "contribRoleCode":null,
            "contribRoleDesc":null,
            "seriesNumber":null,
            "_embeds":null,
            "_links":[

            ]
         },
         ...

BISAC codes in the work product display view

By default, the product display view of Work displays categories from the consumer category set (catSetId=CN). However if you would prefer to display BISAC categories, you can add the parameter "catSetId=BI" to the request.

/domains/PRH.US/works/321749/views/product-display?catSetId=BI

categories":[
   {
      "catId":​3000001130,
      "catDesc":"Fiction - Folklore",
      "catUri":"FIC010000",
      "menuText":"FIC010000",
      "leafNode":true,
      "deepestNode":true,
      "seq":​0
   },
   {
      "catId":​3000002826,
      "catDesc":"Body, Mind & Spirit",
      "catUri":"OCC000000",
      "menuText":"OCC000000",
      "leafNode":false,
      "deepestNode":true,
      "seq":​0
   }
]

BISAC hierarchy

You can use the /categories/views/hierarchy view to return information about the BISAC hierarchy if you set catSetId=BI.

/domains/PRH.US/categories/views/hierarchy?depth=1&catSetId=BI&suppressRecordCount=true


      "categories":[
         {
            "catId":​3000000000,
            "catDesc":"Bisac Parent Node",
            "catUri":null,
            "menuText":null,
            "leafNode":false,
            "children":[
               {
                  "catId":​3000000001,
                  "catDesc":"Antiques & Collectibles",
                  "catUri":"ANT000000",
                  "menuText":"ANT000000",
                  "leafNode":false,
                  "children":null,
                  "parent":null,
                  "countBestsellers":null,
                  "countAwards":null,
                  "countNewReleases":null,
                  "countComingSoon":null
               },
               {
                  "catId":​3000000047,
                  "catDesc":"Architecture",
                  "catUri":"ARC000000",
                  "menuText":"ARC000000",
                  "leafNode":false,
                  "children":null,
                  "parent":null,
                  "countBestsellers":null,
                  "countAwards":null,
                  "countNewReleases":null,
                  "countComingSoon":null
               },
               {
                  "catId":​3000000085,
                  "catDesc":"Art",
                  "catUri":"ART000000",
                  "menuText":"ART000000",
                  "leafNode":false,
                  "children":null,
                  "parent":null,
                  "countBestsellers":null,
                  "countAwards":null,
                  "countNewReleases":null,
                  "countComingSoon":null
               },

To get information about a specific node in the hierarchy, here you do have to use a catId; the catUri parameter is not yet supported.

/domains/PRH.US/categories/views/hierarchy?depth=1&catId=3000000001&suppressRecordCount=true


      "categories":[
         {
            "catId":​3000000001,
            "catDesc":"Antiques & Collectibles",
            "catUri":"ANT000000",
            "menuText":"ANT000000",
            "leafNode":false,
            "children":[
               {
                  "catId":​3000000002,
                  "catDesc":"Antiques & Collectibles - Americana",
                  "catUri":"ANT001000",
                  "menuText":"ANT001000",
                  "leafNode":true,
                  "children":null,
                  "parent":null,
                  "countBestsellers":null,
                  "countAwards":null,
                  "countNewReleases":null,
                  "countComingSoon":null
               },
               {
                  "catId":​3000000003,
                  "catDesc":"Antiques & Collectibles - Art",
                  "catUri":"ANT002000",
                  "menuText":"ANT002000",
                  "leafNode":true,
                  "children":null,
                  "parent":null,
                  "countBestsellers":null,
                  "countAwards":null,
                  "countNewReleases":null,
                  "countComingSoon":null
               },

On Tuesday November 10, 2015, version 1.1.12 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.12 release notes

This was a minor release with a couple small fixes. The recently added "cartonQuantity" element got added to the Work product display view and two new views were added for the Narrative project, /search/views/ant and /works/views/ant. See the Search and Work documentation pages for more more information.

Bug

• [RHAPI-377] - seoFriendlyUrl null in event docType in search

New Feature

• [RHAPI-371] - Add "cartonQty" to the work product display view

Task

• [RHAPI-370] - Create search view for ANT

On Friday November 6, 2015, version 1.1.11 of the Enhanced PRH API was released to production. The IO Docs have been updated to reflect new parameters. If you encounter any problems with your applications as a result of these changes, please contact us at api@penguinrandomhouse.com.

Version 1.1.11 release notes

Retail links added

When a user asked us recently about retail links we had to report that unfortunately they were not available in the API. Well thanks to some help from our colleague Mike Yacullo, we are happy to announce the addition of a /retaillinks sub-resource which can be accessed off a specific title, e.g./domains/PRH.US/titles/9780140056433/retaillinks. This generates a list of links to various retailers and can accept an affiliateSiteId to tailor which affiliate gets credit for the link (see documentation).

Other changes

The Title representation gained a new element, cartonQuantity, which gives the number of books per carton and comes from SAP.

List requests got a new parameter option, catSeq. This integer value can be specified multiple times and targets the seq value on the Title-Category join table. It can be used to restrict which joins are considered when you're listing titles from category or vice versa. For example if you wanted to return titles for which "Epic Fantasy" was only the first category, you could request:

/domains/PRH.US/titles?catUri=/epic-fantasy&catSeq=1

Bug fixes

A couple of the bug fixes are worth noting. RHAPI-361 was about an issue with the /authors endpoint when multiple Author ID values were specified. The count returned was correctly two but there were two copies of each author record. This has been fixed.

RHAPI-367 reported an issue where the /works endpoint was reporting the number of ISBNs rather than the number of works. This was fixed with a modification to the SQL.

Bug

• [RHAPI-353] - Links exposed in search results improper
• [RHAPI-354] - Alternate author link should be suppressed when clientSourceId = 0
• [RHAPI-361] - Incorrect cardinality of /authors
• [RHAPI-367] - Work count incorrect

New Feature

• [RHAPI-349] - Add "cartonQty" to the TItle representation
• [RHAPI-359] - Expose retailer links as a title subresource
• [RHAPI-363] - Add "catSeq" parameter to restrict category matches

Task

• [RHAPI-348] - Add "series.minPrintScore" parameter for /series
• [RHAPI-360] - Please add an onsaledate for the frontlistiest title in the works/views/list-display

Over the past week, we've added two new pages to the Concepts section of the documentation, one titled Print score dealing with issues of how to filter and sort lists of works based on how many have been printed and the other titled Multiple authors which explains why you'll find more than one author record with the same name and how to deal with it. These topics had come up in questions e-mailed to the API team and it seemed appropriate to write up a more detailed explanation for the benefit of all the users.

On Wednesday October 28, 2015, version 1.1.10 of the Enhanced PRH API was released to production. The IO Docs have been updated to reflect new parameters. If you encounter any problems with your applications as a result of these changes, please contact us at api@penguinrandomhouse.com.

Version 1.1.10 release notes

This is a minor bug fix release timed mostly to support changes PRH.com is pushing to production.

Bug

• [RHAPI-357] - series.minPrintScore breaks series/views/list-display

New Feature

• [RHAPI-335] - Add ability to filter series by eBook Original

Task

• [RHAPI-356] - Pull insight flag from INSIGHT_TITLE instead of from TITLE.INSIGHT

On Monday October 26, 2015, version 1.1.9 of the Enhanced PRH API was released to production. The IO Docs have been updated to reflect new parameters. If you encounter any problems with your applications as a result of these changes, please contact us at api@penguinrandomhouse.com.

Version 1.1.9 release notes

This version contains a number of bug fixes including displaying links to the authors of an event and ordering the ISBN content maps in the work product display view by frontlistiest sequence.

Multiple authors

The major change with this version is the addition of the company and clientSourceId to the Author representation and the exposure of companyCode as a search (and predictive search) parameter. When an author writes books for both core a PRH division and one or more of our distribution clients, then the same author is represented by different IDs to allow for the distribution clients to attach their own content to the author. Unfortunately this results in searches returning multiple instances of the same author.

/domains/PRH.US/search?q=janet+evanovich

      {
        "docType": "author",
        "id": "author-8240-PRH.US",
        "key": "8240",
        "name": "Janet Evanovich",
        "score": 12.884931,
        "url": "\/authors\/8240\/janet-evanovich",
        "domain": [
          "PRH.US"
        ],
        "title": null,
        "description": null,
        "author": null,
        "authorFirst": "Janet",
        "authorLast": "Evanovich",
        "photoCredit": "Roland Scarpa",
        "onTour": true,
        "seriesAuthor": null,
        "seriesIsbn": null,
        "seriesCount": null,
        "_links": [
          
        ],
        "_embeds": null
      },
      {
        "docType": "author",
        "id": "author-223351-PRH.US",
        "key": "223351",
        "name": "Janet Evanovich",
        "score": 12.884931,
        "url": "\/authors\/223351\/janet-evanovich",
        "domain": [
          "PRH.US"
        ],
        "title": null,
        "description": null,
        "author": null,
        "authorFirst": "Janet",
        "authorLast": "Evanovich",
        "photoCredit": null,
        "onTour": false,
        "seriesAuthor": null,
        "seriesIsbn": null,
        "seriesCount": null,
        "_links": [
          
        ],
        "_embeds": null
      },

We can see the differences by pulling up their author records.

/domains/PRH.US/authors?authorId=8240&authorId=223351

      {
        "authorId": 8240,
        "display": "Janet Evanovich",
        "first": "Janet",
        "last": "Evanovich",
        "company": {
          "key": "R_H",
          "value": null
        },
        "clientSourceId": 0,
        "seoFriendlyUrl": "\/authors\/8240\/janet-evanovich",
        "contribRoleCode": null,
        "contribRoleDesc": null,
        "_links": [
          
        ],
        "_embeds": null
      },
      {
        "authorId": 223351,
        "display": "Janet Evanovich",
        "first": "Janet",
        "last": "Evanovich",
        "company": {
          "key": "EK",
          "value": "Dark Horse Comics"
        },
        "clientSourceId": 8240,
        "seoFriendlyUrl": "\/authors\/223351\/janet-evanovich",
        "contribRoleCode": null,
        "contribRoleDesc": null,
        "_links": [
          
        ],
        "_embeds": null
      },

The 8240 Janet Evanovich is the core PRH author and has a company.key of "R_H" while the 223351 is the distribution author for "Dark Horse Comics" and has a company.key of "EK", the division code for "Dark Horse Comics". Also notice that the distribution author references the original author ID record from which it was copied in its clientSourceId. For more information on multiple authors, except a new Concepts page on this topic in the next couple of days.

Bug

• [RHAPI-317] - predictive search error
• [RHAPI-332] - work view product display error on DEV
• [RHAPI-334] - Events representation missing author link
• [RHAPI-338] - Series list display view error
• [RHAPI-344] - Add seriesCount to Predictive Search Display View
• [RHAPI-346] - Author display view not honoring "rows" parameter

New Feature

• [RHAPI-337] - Preserve frontlistiest order for ISBN maps in work product display view

Task

• [RHAPI-304] - Expose AUTHOR.CLIENT_SOURCE_ID in author representation
• [RHAPI-305] - Add "companyCode" parameter to /search
• [RHAPI-309] - Add seriesCount to Search Display View
• [RHAPI-340] - Change unknown parameter log level

Sub-task

• [RHAPI-330] - Add seoFriendlyUrl to work list display
• [RHAPI-331] - Add "companyCode" parameter to /search/predictive as well

On Tuesday October 13, 2015, version 1.1.8 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.8 release notes

This version is mostly small bug fixes relating to work PRH.com is doing on their series pages. One other change was the addition of links with the icon rel to various Title, Work and Author views so that related cover images and author photos can be accessed without having to construct URLs on the client side.

Bug

• [RHAPI-316] - work product display view error in BaseCalendar.getCalendarDateFromFixedDate
• [RHAPI-319] - Issues with other-series view
• [RHAPI-320] - Work list not returning the frontlistiest in the work representation
• [RHAPI-324] - Only pull SERIESxCATEGORY categories from the frontlistiest ISBN of the representative work

Task

• [RHAPI-321] - Add image link to author, title and work views

I wanted to draw attention to the fact that we've been updating and enhancing our documentation. In the past month, we've moved the API documentation from our internal TechWiki to this Mashery portal. This documentation complements the interactive IO Docs which allow you to make calls against the API and see actual results. As the API gets more use, we're getting lots of good questions about how to find and interpret the data. We're using the concepts area of the docs section of this portal to answer those questions with explanations and examples.