Categories

Penguin Random House titles are assigned to one or more categories identified by a numeric catId. Each category is part of a larger category set and may be arranged in relation to other categories in the set to form a hierarchy.

Category sets

Category sets are identified by a two-character code called a catSetId. Both the Consumer (CN) category set used by the Penguin Random House web site and the Penguin.com (PG) category set are mapped from the BISAC (BI) categories associated with an ISBN along with other meta-data such as format and imprint.

Requests

Category lists can be generated from the following endpoint.

/domains/{domain}/categories

You can also get the categories associated with another resource by adding 'categories' to the path

/domains/{domain}/titles/{isbn}/categories
/domains/{domain}/authors/{authorId}/categories 

Details about a specific category can be fetched by adding the catId to the path.

/categories/{catId}
/domains/{domain}/categories/{catId}

Category listings are always across all category sets unless one or more 'catSetId' parameters are specified.

Representation

        "catId": 2000000047,
        "description": "Epic Fantasy",
        "catUri": "\/epic-fantasy",
        "menuText": "Epic",
        "hasChildren": false,

• catId: a number that uniquely identifies this category
• description: the description of the category, suitable for display
• catUri: a unique identifier for this category that is used to drive the category-specific URLs on the PRH.com site; this value can be used as a filter using the catUri parameter
• menuText: a brief description of the category, suitable for use in a navigational menu
• hasChildren: a boolean that is true if this category is a member of a hierarchical category set and that hierarchy specifies this category as a parent to one or more categories
• seq: (optional) when displayed in the context of an ISBN or Work ID, the sequence that this category was assigned (if any); see the section "Category sequencing" below for more information
• weight: (optional) when displayed in the context of an ISBN or Work ID, the weight that this category has for that particular title; see the section "Category weights" below for more information

Category hierarchies

You can extract the hierarchical relationships within a category set using the hierarchy view.

/domains/{domain}/categories/views/hierarchy?catSetId=CN&depth=2
/domains/{domain}/categories/views/hierarchy?catId=2000000054&depth=1

Note that hierarchy requests can take a while to return so using depth to limit the number of records to return is encouraged. Another suggestion is to add '&suppressRecordCount=true' to the request so that the PRH.com filter counts are not computed which can save a lot of time.

Category assignments for hierarchical sets

Titles are assigned to all the levels of the category hierarchy. For example, if a book is mapped to the "Epic Fantasy" consumer category, then it will also be in its parent category "Fantasy" and its grandparent "Fiction" as well. That way if you do a search or a listing at any level of the hierarchy you'll get a hit for that title. However it also means that if you retrieve the consumer categories for a title, you will get back categories at all levels in the hierarchy. Typically you would want to restrict your display to just the most specific categories in each branch of the hierarchy.

If you fetch the hiearchy ahead of time and store its structure, you can identify the most specific nodes from the element leafNode in the representation. This is a boolean that is true for categories that have no children in the hierarchy. However titles are not always mapped to leaf nodes. For some titles, the "Fantasy" category may be the most specific assignment in that branch even though "Fantasy" itself has children underneath it. Instead of having three categories returned ("Epic Fantasy", "Fantasy" and "Fiction"), it would just have two ("Fantasy" and "Fiction") and of those two the most specific would be "Fantasy". 

For example ISBN 9780140074314 The Neverending Story by Michael Ende has a first BISAC code of FIC009000 ("Fiction - Fantasy - General") which results in two consumer category mappings, "Fantasy" (catId=2000000054) and "Fiction" (catId=2000000057). A request for the CN categories of ISBN 9780140074314 will result in both categories being returned. In order to identify "Fantasy" as the most specific, we'll need to use sequencing.

Category sequencing

Some category sets are sequenced such that the first category should be considered more relevant or important than the last. Not all category sets include sequencing, for exampleLibraryThing tags (TX)  and Themes (TM). However at Penguin Random House, each title (i.e. ISBN) is assigned up to three BISAC (BI) codes in a specific order. That order then drives the sequencing of the mapped sets,Consumer (CN) and Penguin.com (PG) although other rules come into effect there as well.

Since the sets that are sequenced also are hierarchical, it is important to understand that sequence numbers of zero indicate a category that is not the most specific for that group. Inversely, any sequence number greater than zero indicates that category is the most specific category in that branch of the hierarchy for that title.

Tip: Identify the most specific categories of a title or work by testing for a 'seq' value greater than 0.

In our example above, the categories for ISBN 9780140074314 based on just the first BISAC code were "Fantasy" and "Fiction". That books' second BISAC code, FIC019000 ("Fiction - Literary"), results in two more consumer category mappings, "Literary Fiction" (catId=2000000083) and "Fiction" (catId=2000000057). But since "Fiction" is a duplicate we'll only get back three categories when we fetch them for this title.

/domains/PRH.US/titles/9780140074314/categories?catSetId=CN

"categories": [
      {
        "catId": 2000000054,
        "description": "Fantasy",
        "catUri": "\/fantasy",
        "menuText": "Fantasy",
        "hasChildren": true,
        "seq": 1,
        "weight": 0,
        "_embeds": null,
        "_links": [
          
        ]
      },
      {
        "catId": 2000000056,
        "description": "Teen & Young Adult Fantasy Fiction",
        "catUri": "\/fantasy-teen-young-adult-fiction",
        "menuText": "Fantasy & Magical",
        "hasChildren": false,
        "seq": 3,
        "weight": 0,
        "_embeds": null,
        "_links": [
          
        ]
      },
      {
        "catId": 2000000057,
        "description": "Fiction",
        "catUri": "\/fiction",
        "menuText": "Fiction",
        "hasChildren": true,
        "seq": 0,
        "weight": 0,
        "_embeds": null,
        "_links": [
          
        ]
      },
      {
        "catId": 2000000058,
        "description": "Teen & Young Adult Fiction ",
        "catUri": "\/fiction-teen-young-adult",
        "menuText": "Fiction",
        "hasChildren": false,
        "seq": 4,
        "weight": 0,
        "_embeds": null,
        "_links": [
          
        ]
      },
      {
        "catId": 2000000083,
        "description": "Literary Fiction",
        "catUri": "\/literary-fiction",
        "menuText": "Literary",
        "hasChildren": false,
        "seq": 2,
        "weight": 0,
        "_embeds": null,
        "_links": [
          
        ]
      },
      {
        "catId": 2000000166,
        "description": "Teen & Young Adult",
        "catUri": "\/teen-young-adult",
        "menuText": "Teen & Young Adult",
        "hasChildren": true,
        "seq": 0,
        "weight": 0,
        "_embeds": null,
        "_links": [
          
        ]
      }
    ],

You can see in the response that "Fantasy" has a seq=1 and "Literary Fiction" has seq=2 while "Fiction" is seq=0 which identifies it as a member of the consumer hierarchy that does not necessarily need to be displayed.

Sorting by sequence

Note that the example above is not sorted in order. We can solve that by specifying the 'sort' parameter with the value 'seq' which not only orders by the category sequence but also restricts the display to just those categories that have a sequence greater than zero.

/domains/PRH.US/titles/9780140074314/categories?catSetId=CN&sort=seq

"categories": [
      {
        "catId": 2000000054,
        "description": "Fantasy",
        "catUri": "\/fantasy",
        "menuText": "Fantasy",
        "hasChildren": true,
        "seq": 1,
        "weight": 0,
        "_embeds": null,
        "_links": [
          
        ]
      },
      {
        "catId": 2000000083,
        "description": "Literary Fiction",
        "catUri": "\/literary-fiction",
        "menuText": "Literary",
        "hasChildren": false,
        "seq": 2,
        "weight": 0,
        "_embeds": null,
        "_links": [
          
        ]
      },
      {
        "catId": 2000000056,
        "description": "Teen & Young Adult Fantasy Fiction",
        "catUri": "\/fantasy-teen-young-adult-fiction",
        "menuText": "Fantasy & Magical",
        "hasChildren": false,
        "seq": 3,
        "weight": 0,
        "_embeds": null,
        "_links": [
          
        ]
      },
      {
        "catId": 2000000058,
        "description": "Teen & Young Adult Fiction ",
        "catUri": "\/fiction-teen-young-adult",
        "menuText": "Fiction",
        "hasChildren": false,
        "seq": 4,
        "weight": 0,
        "_embeds": null,
        "_links": [
          
        ]
      }
    ],

Category weights

Some category sets, such as Library Thing (TA), have a weight value instead of a sequence. You can sort by weight just as you can by sequence.

/domains/BOT/works/108336/categories?catSetId=TA&sort=weight&dir=desc

"categories": [
      {
        "catId": 90000035069,
        "description": "fantasy",
        "catUri": null,
        "menuText": null,
        "hasChildren": false,
        "seq": 0,
        "weight": 3259,
        "_embeds": null,
        "_links": [
          
        ]
      },
      {
        "catId": 90000034177,
        "description": "epic",
        "catUri": null,
        "menuText": null,
        "hasChildren": false,
        "seq": 0,
        "weight": 288,
        "_embeds": null,
        "_links": [
          
        ]
      },
      {
        "catId": 90000074123,
        "description": "a song of ice and fire",
        "catUri": null,
        "menuText": null,
        "hasChildren": false,
        "seq": 0,
        "weight": 278,
        "_embeds": null,
        "_links": [
          
        ]
      },
      ...
    ],