Category resource

This resource returns information about categories.

See also Concepts - Categories

Specifications

List categories

Return a list of category objects.

/categories

Typically you will want to restrict this list to just the categories of a particular category set.

/categories?catSetId=CN

Get category

Return a single category object.

/categories/{catId}

Get category children

Return a list of category objects that are children of the specified category.

/categories/{catId}/children

Get category parent

Return a single category object that is the parent of the specified category

/categories/{catId}/parent

Related information

These subresource specifications will return data of different forms related to the specified category.

/categories/{catId}/authors
/categories/{catId}/series
/categories/{catId}/titles
/categories/{catId}/works

Parameters

The base endpoint produces a list of categories and accepts all of the common work filter parameters with the interpretation "return the distinct categories that are linked to the works matching the supplied criteria".

In addition, there are some parameters specific to the category list request. 

catSetId

(list) return categories in the specified category set

Representation

Here is a sample response.

/categories/2000000054

        "catId": 2000000054,
        "description": "Fantasy",
        "catUri": "\/fantasy",
        "menuText": "Fantasy",
        "hasChildren": true,

Additional fields

If you specify a category in the context of a work or a title, the seq element from the join table will be added to the representation

/domains/PRH.US/works/321749/categories?catSetId=CN

    "categories": [
      {
        "catId": 2000000053,
        "description": "Fairy Tales",
        "catUri": "\/fairy-tales",
        "menuText": "Fairy Tales",
        "hasChildren": false,
        "seq": 1,
        "_embeds": null,
        "_links": [
          
        ]
      },
      {
        "catId": 2000000054,
        "description": "Fantasy",
        "catUri": "\/fantasy",
        "menuText": "Fantasy",
        "hasChildren": true,
        "seq": 0,
        "_embeds": null,
        "_links": [
          
        ]
      },
      {
        "catId": 2000000057,
        "description": "Fiction",
        "catUri": "\/fiction",
        "menuText": "Fiction",
        "hasChildren": true,
        "seq": 0,
        "_embeds": null,
        "_links": [
          
        ]
      },
      {
        "catId": 2000000111,
        "description": "Nonfiction",
        "catUri": "\/nonfiction",
        "menuText": "Nonfiction",
        "hasChildren": true,
        "seq": 2,
        "_embeds": null,
        "_links": [
          
        ]
      },
      {
        "catId": 2000000120,
        "description": "Philosophy",
        "catUri": "\/philosophy",
        "menuText": "Philosophy",
        "hasChildren": false,
        "seq": 3,
        "_embeds": null,
        "_links": [
          
        ]
      }
    ],

Views

Product hierarchy

For some category sets, the categories are put in relation to each other in a hierarchy. This view outputs all or some of that hierarchy.

/categories/views/hierarchy

Parameters

Either catSetId or catId must be specified so that the view has an anchor in a particular hierarchy.

catSetId

display the hierarchy for the specified category set

catId

display the hierarchy starting from a particular category

depth

(numeric, default=0) the number of levels of children to include

A note on BANC counts

The BANC (Bestsellers,Awards,New Releases,Coming Soon) counts are added as a feature for PRH.com. If you don't need those counts, you may use the suppressRecordCount=true to save significant time rendering the result. Alternatively you can omit a domain specification so that the back end is not able to list titles and the counts will all be zero.

Example with catSetId

/categories/views/hierarchy?catSetId=CN&depth=1

    "categories": [
      {
        "catId": 2000000000,
        "catDesc": "Consumer Category",
        "catUri": null,
        "menuText": null,
        "leafNode": false,
        "children": [
          {
            "catId": 2000000029,
            "catDesc": "Children's Books",
            "catUri": "\/childrens",
            "menuText": "Children's",
            "leafNode": false,
            "children": null,
            "parent": null,
            "countBestsellers": 0,
            "countAwards": 0,
            "countNewReleases": 0,
            "countComingSoon": 0
          },
          {
            "catId": 2000000057,
            "catDesc": "Fiction",
            "catUri": "\/fiction",
            "menuText": "Fiction",
            "leafNode": false,
            "children": null,
            "parent": null,
            "countBestsellers": 0,
            "countAwards": 0,
            "countNewReleases": 0,
            "countComingSoon": 0
          },
          {
            "catId": 2000000167,
            "catDesc": "Humor",
            "catUri": "\/humor",
            "menuText": "Humor",
            "leafNode": true,
            "children": null,
            "parent": null,
            "countBestsellers": 0,
            "countAwards": 0,
            "countNewReleases": 0,
            "countComingSoon": 0
          },
          {
            "catId": 2000000086,
            "catDesc": "Merchandise",
            "catUri": "\/merchandise",
            "menuText": "Merchandise",
            "leafNode": true,
            "children": null,
            "parent": null,
            "countBestsellers": 0,
            "countAwards": 0,
            "countNewReleases": 0,
            "countComingSoon": 0
          },
          {
            "catId": 2000000111,
            "catDesc": "Nonfiction",
            "catUri": "\/nonfiction",
            "menuText": "Nonfiction",
            "leafNode": false,
            "children": null,
            "parent": null,
            "countBestsellers": 0,
            "countAwards": 0,
            "countNewReleases": 0,
            "countComingSoon": 0
          },
          {
            "catId": 2000000123,
            "catDesc": "Poetry",
            "catUri": "\/poetry",
            "menuText": "Poetry",
            "leafNode": true,
            "children": null,
            "parent": null,
            "countBestsellers": 0,
            "countAwards": 0,
            "countNewReleases": 0,
            "countComingSoon": 0
          },
          {
            "catId": 2000000166,
            "catDesc": "Young Adult",
            "catUri": "\/young-adult",
            "menuText": "Young Adult",
            "leafNode": false,
            "children": null,
            "parent": null,
            "countBestsellers": 0,
            "countAwards": 0,
            "countNewReleases": 0,
            "countComingSoon": 0
          }
        ],
        "parent": null,
        "countBestsellers": 0,
        "countAwards": 0,
        "countNewReleases": 0,
        "countComingSoon": 0
      }
    ],

Example with catId

/categories/views/hierarchy?catId=2000000054&depth=1

    "categories": [
      {
        "catId": 2000000054,
        "catDesc": "Fantasy",
        "catUri": "\/fantasy",
        "menuText": "Fantasy",
        "leafNode": false,
        "children": [
          {
            "catId": 2000000034,
            "catDesc": "Contemporary Fantasy",
            "catUri": "\/contemporary-fantasy",
            "menuText": "Contemporary ",
            "leafNode": true,
            "children": null,
            "parent": null,
            "countBestsellers": 0,
            "countAwards": 0,
            "countNewReleases": 0,
            "countComingSoon": 0
          },
          {
            "catId": 2000000047,
            "catDesc": "Epic Fantasy",
            "catUri": "\/epic-fantasy",
            "menuText": "Epic",
            "leafNode": true,
            "children": null,
            "parent": null,
            "countBestsellers": 0,
            "countAwards": 0,
            "countNewReleases": 0,
            "countComingSoon": 0
          },
          {
            "catId": 2000000053,
            "catDesc": "Fairy Tales",
            "catUri": "\/fairy-tales",
            "menuText": "Fairy Tales",
            "leafNode": true,
            "children": null,
            "parent": null,
            "countBestsellers": 0,
            "countAwards": 0,
            "countNewReleases": 0,
            "countComingSoon": 0
          },
          {
            "catId": 2000000155,
            "catDesc": "Urban Fantasy",
            "catUri": "\/urban-fantasy",
            "menuText": "Urban ",
            "leafNode": true,
            "children": null,
            "parent": null,
            "countBestsellers": 0,
            "countAwards": 0,
            "countNewReleases": 0,
            "countComingSoon": 0
          }
        ],
        "parent": {
          "catId": 2000000057,
          "catDesc": "Fiction",
          "catUri": "\/fiction",
          "menuText": "Fiction",
          "leafNode": false,
          "children": null,
          "parent": null,
          "countBestsellers": 0,
          "countAwards": 0,
          "countNewReleases": 0,
          "countComingSoon": 0
        },
        "countBestsellers": 0,
        "countAwards": 0,
        "countNewReleases": 0,
        "countComingSoon": 0
      }
    ],