Microsoft Graph API for taxonomy (beta) + SPFx

Geek Culture
Published in
4 min readJun 20, 2021

In this short post we will take a look at how to consume the Microsoft Graph API for taxonomy in SPFx web parts. This endpoint is currently in beta.

Taxonomy Graph API

The Microsoft Graph API for taxonomy helps us to perform CRUD operations on the taxonomy data present in our Microsoft 365 tenant. More details about this can be found here.

The taxonomy data can be used in several places for several purposes in SharePoint sites. It helps us in classifying the SharePoint content in such a way that users will be able to get to the content they require faster. Since taxonomy plays an important role in SharePoint, understanding how to interact with taxonomy in SPFx would be very helpful for us so that we can develop web parts / extensions to handle various scenarios related to taxonomy.

Sample code

In this blog we will look at a scenario in which we will read the data from taxonomy using Microsoft Graph. All the code explained in the blog can be found here.

Cascading taxonomy dropdowns using SPFx

In order to explain the usage of the taxonomy API, let’s assume the following:

  1. A term group named “1 company”
  2. A term set named “Our location”
  3. Parent terms as countries — France, Germany, India and UK
  4. 1st level Child terms as cities — London and Manchester.

We will see how to read all the parent terms (countries) from a term set and then how to read all the child terms (cities) under a parent term.

Using the taxonomy API

The SPFx web part is developed using React hooks and accepts only one property as input and that is the ID of the term set (Our locations).

When the web part loads, we get all the countries (parent terms) present under “Our location” (term set). This can be seen in the getCountries method. In that method we call the List children endpoint of the term set taxonomy API which will list the first level children under a term set — which in this is case is all the countries. We then populate those countries in a country dropdown.

When a country is selected from a the dropdown, we get all the cities (child terms) of the selected country — the _onCountryChange method. We call the List children endpoint of the term taxonomy API which will list the first level children present under a term — in this case all the cities. These are the populated in the city dropdown.

At the time of writing this post getting the custom properties of a term from taxonomy API was not possible. Hence description of a term was used to store data associated with a term.

However we can now access “Shared Custom Properties” of a term using the taxonomy API by adding “properties” to the “$select” clause.

In this scenario we store the co-ordinates of a city in the description. We use that data to show the exact location in the PnP SPFx map control.

To send a request to Microsoft Graph, we use a helper class. This was created by Mikael Svenson and it can be used in any SPFx project. This class has 4 methods to perform CRUD operations using Microsoft Graph.


In the scenario explained here, the data in the taxonomy doesn’t change when the user is interacting with the web part. Hence to improve performance, it makes sense to cache the data instead of calling the taxonomy API each and every time. When we get the city terms under a country we can store them in cache (local storage). To do that we use a class that has methods related to adding data to local storage and fetching data from local storage when needed.


Thanks to the Microsoft Graph team we are now able to interact with the taxonomy data. In this blog post we have seen a simple way to read the data in SPFx web part. This web part can be easily extended to create/update/delete taxonomy data as well. All this is now easily possible with the help of the various taxonomy endpoints provided by this API.



Geek Culture

Microsoft MVP. M365 Developer Architect at Content+Cloud.