Skip to main content

How to get Search Refiners using REST API

As Title says this blog is about getting SharePoint Search Refiners using REST API. I could not find examples in internet for getting refiners and how to read refiner JSON data. So I did kind of research and trials and finally I was able to get the refiners using REST API. I assume that you are already familiar with fetching search results using REST API. If not, I suggest to read this fantastic post by Chris O'Brien. I have extended the example given in this blog to refiners.

Let us first understand how to frame REST query to get refiners. The syntax of the URL is

http://[your site]/_api/search/query?querytext='SharePoint'&refiners='[refiner]'

To get refiners, refiners keyword should be passed as a parameter along with the actual refiner that we need. Before I show an example, let us first check how XML response would look like if you don't add this keyword.
Without Refiner
As marked in Red, if we don't pass refiner as parameter, RefinemenetResults will return NULL.

Now, I'll pass File Size as a refiner to the REST query and it looks like this:

http://[your site]/_api/search/query?querytext='SharePoint'&refiners='Size'

One point to be noted here is: The refiner here refers to managed property which was made as "Refinable". Now the XML response looks something like this:
With Refiner
We can see loads of data under RefinementResults element. We can also see 4 values for Size refiner under Refiners element.

Now how do we get this data in JSON format? Again I assume that you are aware of getting data into JSON format from REST API output. I'll jump into the exact code to read the refiner data.

var refinements = jsonObj.d.query.PrimaryQueryResult.RefinementResults.Refiners.results[0].Entries.results;
var searchRefinementHtml = '';

$.each(refinements, function (index, refinement) {
            searchRefinementHtml += "

" + refinement.RefinementValue + " (" + refinement.RefinementCount + ")" + "


Here I am trying to list the refiner values. First I am getting the refinement results into a variable. Within the loop, I'm reading properties of each refiner. I've highlighted two properties which are of our interest. RefinementValue and RefinementCount. Similarly we can look at XML output and get any other property of refiner. My refiner output looks like this:
Display Refiner
You can use RefinementToken property to implement further filtering based on refiner. You can also pass multiple refiners to the query and get the response. In this query, Size and DisplayAuthor are passed.

http://[your site]/_api/search/query?querytext='SharePoint'&refiners='Size,DisplayAuthor'

The output looks like this. I've collapsed the details.
Multiple Refiners
That's it for now! Happy searching! 


  1. Hi Suresh,

    I know this is an old post, but it is good stuff. One question I have is how to further refine your results using the refinement token. What is the syntax? What are my expected results?

  2. Hi Clint,

    Have you tried the syntax provided in the below MSDN article? It uses RefinementFilters to add a filter on refinement token.

    1. Hi Suresh,

      Thanks for the response. I had looked at that article. I think what initially confused me was that the article seemed to indicate that the refinement token and the refinement name needed to be concatenated to get a filter value. In my case, the refinement name and the refinement token are virtually identical; the token is simply the refinement name in Hex. I guess I was expecting the refinement token to be a token to somehow access an already processed query, but I've since determined that is not the case.

    2. To continue my thought above, I still need to resubmit my original query to the search API, then I add the Refinement Filter based on the refinement data that was returned from my original query.

  3. Hi Suresh,
    Thanks for your wonderful posting !!...
    I am able to get Refiners list and Relevant results, but unable to find the mapping between relevant result items with 'customer' refiners.
    For e.g: DisplayAuthor is one default refinement and is the tag name that I am getting in Relevant result, so I am able to map it. But for a custom refinement, there is no tag present in Relevant result

    1. @Unknown, is it a custom managed property? Can you share how your query looks like?


Post a Comment