SharePoint Search REST API. GET and POST requests

SharePoint Search provides REST query API that can be used to access search results. In other words, SharePoint search may be as a read-only data source which provides all the data you have (list items, documents, user profiles, and Office 365 services based on SharePoint such as Planner, Groups, Project Online and others)

In this post, I show how to use the SharePoint Search REST API to build up custom solutions.

Search APIs

There are many APIs to process search queries in SharePoint 2013/2016/Online:

• .NET Server-side object model (SSOM) - old school approach for farm solutions. Not applicable for SharePoint Online
• .NET Client-side object model (CSOM) - for client .NET applications
• Silverlight CSOM - do not use this even somebody makes you do this
• JavaScript object model (JSOM) - sp.search.js and sp.search.app.js libraries. Topic for my future posts REST endpoints - subject of the current post

Search Parameters

Parameters of a query (Source: SharePoint Search REST API overview)

Search REST API. GET requests

Base URL for a GET request is the following:

{siteUrl}/_api/search/query

As you can see there are 45 parameters that we can use to get relevant search results. Therefore it's easy to run into bad request error.

So let's dive into SharePoint Search REST API POST request.

Search REST API. POST requests

Base URL for POST request is the following:

{siteUrl}/_api/search/postquery

Prerequisites

In my samples, I'll use jQuery to perform search queries and show results on a page.

<script src="https://cdnjs.cloudflare.com/ajax/libs/angular.js/1.6.5/angular.min.js"&gt;&lt;/script>

Hello World

First of all here is a simple search POST request in SharePoint:

// SharePoint Search Query
var searchQuery = {
    request: {
        Querytext: "*"
    }
};

// Request Body
var postQuery = {
    /* static part of the query*/
    method: 'POST',
    url: "/_api/search/postquery",
    headers: {
        "Accept": "application/json",
        "Content-Type": "application/json",
        "X-RequestDigest": $("#__REQUESTDIGEST").val()
    },
    /* /static part of the query*/

    // search query
    data: JSON.stringify(searchQuery)
};

// jQuery AJAX
$.ajax(postQuery).done((response) => {
    console.log(response);
});

Response for the first query:

RelevantResults object contains Table object. The Table object contains an array of Row objects. Each Row object contains an array of Cell. At last, Cell object contains values:

The same response we could get for GET request. The only difference is the HTTP method (GET, POST) we performed.

Query. Select Properties

Selected properties must be passed as array of string:

var searchQuery = {
    request: {
        Querytext: "*",
        SelectProperties: [
            "Title", "ListID", "ListItemID", "Author"
        ]
    }
};

Query. Paging

There are two parameters which can be used for paging: StartRow (0 by default) and RowLimit (10 by default):

var searchQuery = {
    request: {
        Querytext: "*",
        StartRow: 10,
        RowLimit: 100
    }
};

Query. Source

In search request, you can set the scope in which you need to find out data. Built-in search scope listed in the following table:

Source in SharePoint Search is actually predefined search query transform. For example Picture scope has the following one (filter by ContentTypeId):

{?path:} {?owstaxIdMetadataAllTagsInfo:} (ContentTypeId:0x0101009148F5A04DDD49cbA7127AADA5FB792B00AADE34325A8B49cdA8BB4DB53328F214* OR ContentTypeId:0x010102*)

Query with declared SourceId:

var searchQuery = {
    request: {
        SourceId: "9479bf85-e257-4318-b5a8-81a180f5faa1"
    }
};

Query. Refiners

A simple string which contains comma-separated refiners

var searchQuery = {
    request: {
        Refiners: "DisplayAuthor,FileType"
    }
};

Query. Refiner Filter

Refiner filter passed by an array of FQL filters

var searchQuery = {
    request: {
        RefinementFilters: [
        'DisplayAuthor:"Vitaly Zhukov"',
        'FileType:or("docx", "xlsx")'
    ]
    }
};

Convert Table to an array of objects

To simplify using the search result here is a very short javascript function:

// jQuery AJAX
$.ajax(postQuery).done((response) => {
    console.log(response);
    
    // result array of objects
    var results = [];
    response.PrimaryQueryResult.RelevantResults.Table.Rows.forEach(function (row) {
        // result object
        var item = {};

        row.Cells.forEach(function (cell) {
            // cell.Key = property name for result object
            item[cell.Key] = {
                Value: cell.Value,
                ValueType: cell.ValueType
            };
        })

        // add result object to result array
        results.push(item);
    });
    
    console.log(results);
});

And now we have an array of objects instead of an array of arrays: