Docs

Taxonomy API

Overview

The Taxonomy API lets you manage hierarchies for your product categories. The API will power navigation for your e-commerce site by powering the menus for your visitors to explore different products. It will help your potential buyers to quickly determine the appropriate categories in which to browse for the products they are looking to purchase.

Generally, products in e-commerce are organized in 3 levels of category hierarchies. The navigation paths to a product can be multiple, as a product may belong to more than one category or sub-category.

Let’s look at a sample taxonomy with three levels of hierarchy:

  • Men (Level 1)
    • Shoes (Level 2)
      • Sports shoes (Level 3)
      • Formal shoes (Level 3)
    • Shirts (Level 2)
      • Formal shirts (Level 3)
      • Casual shirts (Level 3)
  • Women (Level 1)
    • Western Wear (Level 2)
      • Dresses & Jumpsuits (Level 3)
      • Trousers & Capris (Level 3)
    • Footwear (Level 2)
      • Heels (Level 3)
      • Boots (Level 3)
  • Kids (Level 1)
    • Boys clothing (Level 2)
      • Dresses & Jumpsuits (Level 3)
      • Trousers & Capris (Level 3)
    • Kids Accessories (Level 2)
      • Watches (Level 3)
      • Boots (Level 3)

In the example above, “Shoes” and “Shirts” are children of “Men”, and siblings of each other. Basically, siblings are children of the same parent. Neighbours for any given node in the taxonomy are its children and siblings. For example, “Shirts”, “Sports Shoes” and “Formal Shoes” are neighbours of “Shoes”.

Unbxd Taxonomy API is designed in a manner that it supports optimal response for all different types of navigation UI on the sites. You can choose different category levels to appear on the top navigation menu and/or the left navigation menu, and configure the API accordingly.

For example, you can choose to view all the three levels on the top navigation menu. Or if there are a lot of level 3 categories, then you can have Level 1 and Level 2 categories on the top navigation panel, and when a shopper clicks on a Level 2 category from the top navigation menu, you can display the left navigation menu with all the Level 3 categories (children of selected Level 2 node). Here, once a shopper clicks on level 2 node, she will have an expanded view of Level 2.

Taxonomy API Format

With taxonomy API, your visitors start their product discovery experience, directly from the navigation menu of your ecommerce store. To integrate this API, you need to make the following API call to Unbxd servers:

https://search.unbxd.io/sites/<sitekey>/taxonomy?depth={1,2,3}  

Get full taxonomy

Format:

GET /sites/<sitekey>/taxonomy?depth=3  

This Taxonomy API call will return a full category tree. It should be called on each page of the website, wherever navigation has to be powered (if not cached).

Get data for a taxonomy node

Format:

GET /sites/<sitekey>/taxonomy/<category_id>/<Path Parameter>  

This will return a category subtree for the specic category node. This request can be used to get only children for a node, only siblings for a node, or both.

Note:
The category_id should be passed as a path parameter that points to the node for which data is requested.

Get Full Taxonomy

The table below describes the parameters to get the full taxonomy.

ParameterDescriptionMandatoryDefault Value
depthIt is a non-negative integral number specifying the maximum depth of the taxonomy tree.no2

Sample Request

This is a sample request for a full category tree.

GET /sites/<sitekey>/taxonomy?depth=3  

Sample Response

This is a sample response for the category tree as shown in example above. Only Mens node response is given below:

{
  "taxonomy": [
    {
      "name": "root",
      "links": [
        {
          "rel": "self",
          "href": "/taxonomy"
        }
      ],
      "categories": [
        {
          "shortdescription": "Mens Apparel",
          "sequence": "1",
          "identifier": "Mens",
          "links": [
            {
              "rel": "self",
              "href": "/taxonomy/5001"
            }
          ],
          "name": "Men",
          "parentid": "0",
          "categories": [
            {
              "shortdescription": "Mens Shoes",
              "sequence": "100",
              "identifier": "Mens:Shoes",
              "links": [
                {
                  "rel": "self",
                  "href": "/taxonomy/5101"
                },
                {
                  "rel": "child",
                  "href": "/taxonomy/5111"
                },
                {
                  "rel": "child",
                  "href": "/taxonomy/5121"
                }
              ],
              "name": "Shoes",
              "parentId": "5001",
              "catgroup_id": "5101",
              "seourl": "/mens-shoes/",
              "seotoken": "mens-shoes-sports-formal",
              "categories": [
                {
                  "shortdescription": "Sports Shoes",
                  "seourl": "/mens-sports-shoes/",
                  "sequence": "111",
                  "links": [
                    {
                      "rel": "self",
                      "href": "/taxonomy/5111"
                    }
                  ],
                  "identifier": "Mens:Shoes:SportsShoes",
                  "parentId": "5101",
                  "name": "sports shoes",
                  "catgroup_id": "5111",
                  "seotoken": "mens-shoes-sports-adidas-nike"
                },
                {
                  "shortdescription": "formal shoes",
                  "seourl": "/mens-formal-shoes/",
                  "sequence": "121",
                  "links": [
                    {
                      "rel": "self",
                      "href": "/taxonomy/5121"
                    }
                  ],
                  "identifier": "Mens:Shoes:FormalShoes",
                  "parentId": "5101",
                  "name": "formal shoes",
                  "catgroup_id": "5121",
                   "seotoken": "mens-shoes-formal-shoes-woodland-bata"
        }
          ]
      },
            {
              "shortdescription": "Mens Shirts",
              "sequence": "200",
              "identifier": "Mens:Shirts",
              "links": [
                {
                  "rel": "self",
                  "href": "/taxonomy/5201"
                },
                {
                  "rel": "child",
                  "href": "/taxonomy/5211"
                },
                {
                  "rel": "child",
                  "href": "/taxonomy/5221"
                }
              ],
              "name": "Shirts",
              "parentId": "5001",
              "catgroup_id": "5201",
              "seourl": "/mens-shirts/",
              "seotoken": "mens-shirts-formal-casual",
              "categories": [
                {
                  "shortdescription": "Formal Shirts",
                  "seourl": "/mens-formal-shirts/",
                  "sequence": "211",
                  "links": [
                    {
                      "rel": "self",
                      "href": "/taxonomy/5211"
                    }
                  ],
                  "identifier": "Mens:Shirts:FormalShirts",
                  "parentId": "5211",
                  "name": "formal shirts",
                  "catgroup_id": "5211",
                  "seotoken": "mens-shirts-formal"
                },
                {
                  "shortdescription": "casual shirts",
                  "seourl": "/mens-casual-shirts/",
                  "sequence": "221",
                  "links": [
                    {
                      "rel": "self",
                      "href": "/taxonomy/5221"
                    }
                  ],
                  "identifier": "Mens:Shirts:CasualShirts",
                  "parentId": "5221",
                  "name": "casual shirts",
                  "catgroup_id": "5221",
                   "seotoken": "mens-shirts-casual" }
               ]
             }
           ]     
         }
       ]
     } 
  ]
}

Specific Taxonomy Node

Path Parameters

The following path parameters enable you to fetch the information for a specific node. You can also get use these params to get children for a node, only siblings for a node, or both.

Path ParametersSample URIDescriptionResponse
/sites/<sitekey>/taxonomy/
Returns only node informationArray of objects. Only one object containing the node information children
children/sites/<sitekey>/taxonomy/
<category_id>/children
Returns node information and children information.Array of objects and the object of the current node will contains array of object (containing children information).
siblings/sites/<sitekey>/taxonomy/
<category_id>/siblings

/sites/<sitekey>/taxonomy/
<category_id>/siblings/
<parent_id>
Returns node information and all the siblings of the passed node and parentid combination. If parentid is not passed, then it returns the children of the first encountered node in the taxonomy. The assumption here is that the siblings will differ for each parentid and node combination. Returns array of objects. Each object will represent a sibling (child of parent) of the node passed.
neighbours/sites/<sitekey>/taxonomy/
<category_id>/neighbours

/sites/<sitekey>/taxonomy/
<category_id>/neighbours/
<parent_id>
Returns children and siblings and node informationReturns an array of objects. Each object will represent a neighbour (child or sibling) of the node passed. And the object of the current node will contain array of objects (containing children information).

Sample Request
This is a sample request for an array of category subtree tree for a taxonomy node.

https://search.unbxd.io/sites/<sitekey>/taxonomy/<category_id>/<path_parameter>  

Sample Response
This is a sample response for an array of category subtree tree for a taxonomy node.

{
  "taxonomy": [
    {
      "name": "root",
      "links": [
        {
          "rel": "self",
          "href": "/taxonomy"
        }
      ],
      "categories": [
        {
          "shortdescription": "Mens Apparel",
          "sequence": "1",
          "identifier": "Mens",
          "links": [
            {
              "rel": "self",
              "href": "/taxonomy/5001"
            }
          ],
          "name": "Men",
          "parentid": "0",
          "categories": [
            {
              "shortdescription": "Mens Shoes",
              "sequence": "100",
              "identifier": "Mens:Shoes",
              "links": [
                {
                  "rel": "self",
                  "href": "/taxonomy/5101"
                },
                {
                  "rel": "child",
                  "href": "/taxonomy/5111"
                },
                {
                  "rel": "child",
                  "href": "/taxonomy/5121"
                }
              ],
              "name": "Shoes",
              "parentId": "5001",
              "catgroup_id": "5101",
              "seourl": "/mens-shoes/",
              "seotoken": "mens-shoes-sports-formal",
              "categories": [
                {
                  "shortdescription": "Sports Shoes",
                  "seourl": "/mens-sports-shoes/",
                  "sequence": "111",
                  "links": [
                    {
                      "rel": "self",
                      "href": "/taxonomy/5111"
                    }
                  ],
                  "identifier": "Mens:Shoes:SportsShoes",
                  "parentId": "5101",
                  "name": "sports shoes",
                  "catgroup_id": "5111",
                  "seotoken": "mens-shoes-sports-adidas-nike"
                },
                {
                  "shortdescription": "formal shoes",
                  "seourl": "/mens-formal-shoes/",
                  "sequence": "121",
                  "links": [
                    {
                      "rel": "self",
                      "href": "/taxonomy/5121"
                    }
                  ],
                  "identifier": "Mens:Shoes:FormalShoes",
                  "parentId": "5101",
                  "name": "formal shoes",
                  "catgroup_id": "5121",
                   "seotoken": "mens-shoes-formal-shoes-woodland-bata"
        }
          ]
      },
            {
              "shortdescription": "Mens Shirts",
              "sequence": "200",
              "identifier": "Mens:Shirts",
              "links": [
                {
                  "rel": "self",
                  "href": "/taxonomy/5201"
                },
                {
                  "rel": "child",
                  "href": "/taxonomy/5211"
                },
                {
                  "rel": "child",
                  "href": "/taxonomy/5221"
                }
              ],
              "name": "Shirts",
              "parentId": "5001",
              "catgroup_id": "5201",
              "seourl": "/mens-shirts/",
              "seotoken": "mens-shirts-formal-casual",
              "categories": [
                {
                  "shortdescription": "Formal Shirts",
                  "seourl": "/mens-formal-shirts/",
                  "sequence": "211",
                  "links": [
                    {
                      "rel": "self",
                      "href": "/taxonomy/5211"
                    }
                  ],
                  "identifier": "Mens:Shirts:FormalShirts",
                  "parentId": "5211",
                  "name": "formal shirts",
                  "catgroup_id": "5211",
                  "seotoken": "mens-shirts-formal"
                },
                {
                  "shortdescription": "casual shirts",
                  "seourl": "/mens-casual-shirts/",
                  "sequence": "221",
                  "links": [
                    {
                      "rel": "self",
                      "href": "/taxonomy/5221"
                    }
                  ],
                  "identifier": "Mens:Shirts:CasualShirts",
                  "parentId": "5221",
                  "name": "casual shirts",
                  "catgroup_id": "5221",
                   "seotoken": "mens-shirts-casual" }
               ]
             }
           ]     
         }
       ]
     } 
  ]
}

Taxonomy Feed API

The Taxonomy Feed API lets you upload a taxonomy full feed file. The taxonomy feed contains categories present in your e-commerce site.

Upload taxonomy

Format:

POST /<sitekey>/upload/taxonomy  

You can use the format above to pass the taxonomy full feed as a .csv file.

Taxonomy Feed API Format
With taxonomy feed API, you can push the taxonomy feed file to Unbxd servers. To integrate with this API, you need to make the following API call to Unbxd servers:

Sample Request
This is a sample request for uploading a taxonomy.

curl -XPUT -H "Content-Type: application/json" "feed.unbxd.io/<sitekey>/taxonomy" --data-binary @./taxonomy.json  

Switch alias

curl -XPOST -H "Content-Type: application/json" "feed.unbxd.io/<sitekey>/taxonomy/admin" -d '{"action":"aliasSwitch"}'  

Sample Response
This is a sample response for an uploaded taxonomy.

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

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