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! 
Labels:

Comments

  1. ClintApril 20, 2016 at 7:28 PM

    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?

    ReplyDelete
  2. SureshApril 21, 2016 at 5:10 PM

    Hi Clint,

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

    https://msdn.microsoft.com/en-us/library/office/ff394639.aspx#SP15_Creating_refined_query

    ReplyDelete
    Replies
    1. ClintApril 23, 2016 at 12:13 AM

      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.

      Delete
    2. ClintApril 23, 2016 at 12:15 AM

      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.

      Delete
  3. UnknownSeptember 23, 2019 at 2:57 PM

    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

    ReplyDelete
    Replies
    1. SureshOctober 23, 2019 at 11:58 AM

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

      Delete

Post a Comment

Popular posts from this blog

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. List of View Styles I will take typical Contact List and Announcement List to explian about these styles. Let us go one by one. Default: This view, as name suggest, is the default style in a view. This is one of the widely seen style ...
1 comment
Read more

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. ListName ListItem" }, "Title": "First Item", " PeopleField Id": "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 peop...
12 comments
Read more

How to get SharePoint List or Library GUID via REST

Sometimes, you would need List or Library GUID to use that in some operation. In such cases, how do you get hold of GUID using REST API? There is a straight-forward end point which you can use: /_api/web/lists/getByTitle('ListTitle')/Id This will return the GUID of a List or Library. There is also another approach. However this approach works only if a List or Library contains at least one item. /_api/web/lists/getByTitle('ListTitle')/items This is a familiar end point which we use to fetch items of a List or Library. To get the GUID from the response, you would do: var listIDTemp = response.data.d.results[0].__metadata.id; var listID = listIDTemp.substring(listIDTemp.lastIndexOf("guid") + 5).split('\'')[0]; As you can see, we are doing string operations to fetch GUID from metadata.id. This contains information only if the response has at least one item.
Post a Comment
Read more