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.


Post a Comment

Popular posts from this blog

How to update Person field with multiple values using REST API

Person or Group field in SharePoint is similar to a Lookup field. When you are updating this field using REST API, you need to append "Id" to the name of the column in the body construct. For example, the body construct looks like this:

data: { "__metadata": { "type": "SP.Data.ListNameListItem" }, "Title": "First Item", "PeopleFieldId": "4" };

The highlighted portions should be replaced by the actual List Name and Column Name. In the above example, the REST call is updating a List item with Title and People columns.

How to get the value for user ID ("4" in the above example) needs a separate explanation and that will be my next post!

The above example works fine if Person field is configured to accept only one value. If we change the Person field to accept multiple values, how do we pass more than one value in the REST call? Since we normally separate user names with semicolon in people picker, I…

All about SharePoint List View Styles

Sometimes, there are out of the box features which we tend to ignore and later when we do apply, we are more than happy about the feature which is readily available in SharePoint. One such feature is List View Style. I never thought I would write a post on this. However, whenever I spoke about this with users, people were excited to see the result. That prompted me to write this post.

Instead of getting into only theory part, I will basically take use cases where these styles can be applied and also touch up on on some minor limitations with certain style.

When you are creating/modifying a List view, you will get an option to select View Style. As shown below, there are 8 options available and Default is always set if you ignore this style.

I will take typical Contact List and Announcement List to explian about these styles. Let us go one by one.

This view, as name suggest, is the default style in a view. This is one of the widely seen style in SharePoint site. This is how it…

Difference between Choice and Lookup fields in SharePoint

When you have to provide users an option of selecting a value from a list, you can go for a Choice field or a Lookup field. Have you ever wondered which one to use and when? Which option should be chosen over other? To address these questions, one need to understand the differences between these two data types in SharePoint. This post outlines these differences to help users decide the appropriate column type based on their needs.

FactorChoiceLookupPermissionTo add values to a Choice field, you need minimum Design permissionTo add values to a Lookup field, you need minimum Contribute/Add permissionChanging existing ValuesIf you change a value in a Choice field, it does not affect the existing values. For example, let us say one of the values was NY and there are items with this value. If you change it to New York in the field schema, it only affects the new values. All existing values will retain NY.If you change a value in a Lookup field, all the existing rows reflect the new value,…