Overview

The Taxonomy API enables clients to create, manage, and retrieve a hierarchical category structure (taxonomy) for a given site. Each site maintains a single taxonomy hierarchy used across the website for navigation, category pages, and SEO routing. The API supports:

• Fetching the entire taxonomy tree.
• Fetching specific nodes, including their children, siblings, or neighbours.
• Uploading the complete taxonomy feed via a bulk ingestion API.

📘

Assumptions & Constraints

1. Each <sitekey> has exactly one taxonomy hierarchy.

2. The taxonomy graph is acyclic (no circular parent-child relationships).

3. Phantom nodes:

• Will not have phantom nodes as parents or children

• Are treated like normal nodes (no semantic distinction at API level)

4. Taxonomy APIs are read-heavy and expected to be cached on the client side

Prerequisites

1. Ensure you have a valid sitekey.
2. Taxonomy data must be ingested successfully using the Taxonomy Feed API.

Headers

Get Full Taxonomy

1. Endpoint: GET /sites/{sitekey}/taxonomy

Description: Returns the complete taxonomy tree up to the specified depth. This API is typically used to power global navigation menus.

2. Query Parameters

• depth = 0 (Only root node)
• depth = 1 (Root + immediate children)

3. Sample Request/ Response

GET /sites/demoSite/taxonomy?depth=3

{
  "taxonomy": [
    {
      "name": "categoryroot",
      "links": [
        {
          "rel": "self",
          "href": "/taxonomy"
        }
      ],
      "categories": [
        {
          "name": "girl",
          "identifier": "Girl:US",
          "parentId": "00000",
          "catgroup_id": "47511",
          "categories": [
            {
              "name": "tops",
              "identifier": "Girl:Tops:US",
              "parentId": "47511",
              "catgroup_id": "49012",
              "categories": [
                {
                  "name": "graphic tees",
                  "identifier": "Girl:Tops:GraphicTees:US",
                  "parentId": "49012",
                  "catgroup_id": "54174"
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}

Get Taxonomy Node Data

1. Endpoint: GET /sites/{sitekey}/taxonomy/{category_id}

Description: Returns taxonomy data for a specific node, based on the requested relationship (node only, children, siblings, or neighbours). This API is commonly used for left navigation menus.

2. Supported Variants
   1. Get Node Info Only: GET /sites/{sitekey}/taxonomy/{category_id}
      Response: Array with a single object containing node information
   2. Get Siblings : GET /sites/{sitekey}/taxonomy/{category_id}/siblings GET /sites/{sitekey}/taxonomy/{category_id}/siblings/{parentId}
      Response: Returns node info + all siblings under the specified parent. If parentId is omitted, siblings are derived from the first matching parent
   3. Get Children: GET /sites/{sitekey}/taxonomy/{category_id}/children
      Response: Returns node info. Node object contains a categories array with all children.
   4. Get Neighbours (Children + Siblings): GET /sites/{sitekey}/taxonomy/{category_id}/neighbours GET /sites/{sitekey}/taxonomy/{category_id}/neighbours/{parentId}
      Response: Current node info, Siblings of the node, Children of the node (embedded)
3. Sample Response

{
  "taxonomy": [
    {
      "name": "girl",
      "identifier": "Girl:US",
      "uniqueID": "47511",
      "categories": [
        {
          "name": "tops",
          "uniqueID": "49012",
          "seoURL": "/us/c/girls-tops-girls-shirts/"
        }
      ]
    },
    {
      "name": "boy",
      "identifier": "Boy:US",
      "uniqueID": "47512"
    }
  ]
}

Taxonomy Feed API

The Taxonomy Feed API is used to upload the complete taxonomy dataset in bulk. The feed is processed asynchronously and indexed for search and navigation.

1. Upload TaxonomyPUT /{sitekey}/taxonomy

Description: Uploads taxonomy data as multiple JSON lines, where each line represents one taxonomy node.

2. Required Field

3. Sample Request

[{
  "_id": "512",
  "name": "Girl",
  "identifier": "Girl",
  "seoURL": "/us/c/girls/",
  "storeID": "10051"
},{
  "_id": "49012",
  "parentId": "512",
  "name": "Tops",
  "identifier": "Girl:Tops",
  "seoURL": "/us/c/girls-tops/",
  "storeID": "10051"
},{
  "_id": "54174",
  "parentId": "49012",
  "name": "graphic tees",
  "identifier": "Girl:Tops:GraphicTees:US",
  "seoURL": "/us/c/girls-tops-girls-shirts-graphic-tees/",
  "storeID": "10051"
}]

{
  "nodeCount": "794",
  "message": "Index creation successful",
  "statusCode": "200"
}

4. Alias Switch: After successful ingestion, switch the taxonomy alias:
   TextRequestResponse

   POST /{sitekey}/taxonomy/admin

   {
     "action": "aliasSwitch"
   }

   {
     "message": "Rename successful",
     "statusCode": "200"
   }

   Error Handling

   Response

   {
     "error": {
       "code": 6001,
       "msg": "invalid category key"
     }
   }

   Error Codes