Penguin Random House Developer Blog
BISAC category improvements
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
},
0 Comments
Please sign in to post a comment.