Search for SharePoint sites with the Microsoft Search API

From time to time you need to search for a SharePoint site. In these days, you have two options with the Graph API:

When using the first option, the endpoint GET /sites?search={query}, the search filter is a free text search that uses multiple properties when retrieving the search results. Disadvantage is that you can't search site by single property like name, display name or based on the description.

The Search API

The Microsoft Search API can be accessed through the /search/query endpoint.

POST https://graph.microsoft.com/v1.0/search/query
Content-Type: application/json

{
  "requests": [
    {
      "entityTypes": [
        "site"
      ],
      "query": {
        "queryString": "contoso"
      },
      "fields": [
        "id",
        "name",
        "displayName",
        "description",
        "webUrl"
      ],
      "from": 0,
      "size": 25
    }
  ]
}

The request body defines the type of the resource to be searched, the fields to be returned, the query terms, or the size of the page to be retrieved.

The query/queryString defines the search query containing the search terms.

Properties supporting searching

The table below shows an overview of the site properties supporting searching. During the searching you need to use a specific keyword related to each property in the query/queryString.

Property Search keyword(s) Is default
createdDateTime created -
description description YES
displayName title, siteTitle YES
lastModifiedDateTime lastModifiedTime -
name siteName YES
webUrl - YES

Search keywords

When no search keyword is specified, the search is carried out on the default search properties of description, displayName, name and webUrl.

Search for sites that contains the term "marketing" either in the description, displayName, name, or in the webUrl

"queryString": "marketing"

Search for sites by the url

"queryString": "\"https://4wrvkx.sharepoint.com/sites/SalesandMarketing\""

Keyword title

Search for the specified term in the displayName property.

Search for site with the exact display name

"queryString": "title:\"Sales and Marketing\""

Search for sites where display name contains a search term

"queryString": "title:mark*"

Keyword siteName

Search for the specified term in the name property.

Search for site with the exact site name

"queryString": "siteName:Mark8ProjectTeam2"

Search for sites where site name contains a search term

"queryString": "siteName:mark*"

Keyword description

Search for the specified term in the description property.

Search for site with the exact description

"queryString": "description:\"Description of Digital Initiative Public Relations\""

Search for sites where description contains a search term

"queryString": "description:initiative"

Keyword created

Supported datetime formats are:

  • YYYY-MM-DD
  • YYYY-MM-DDThh:mm:ss
  • YYYY-MM-DDThh:mm:ssZ
  • MM/DD/YYYY

Search for sites created at the specific day

"queryString": "created:2024-01-03"
"queryString": "created:01/03/2024"

Search for sites created between two dates

"queryString": "created:2020-01-01..2024-01-03"
"queryString": "created:01/01/2020..01/03/2024"
"queryString": "created>=2023-07-01 AND created<=2023-07-03"
"queryString": "created:2023-07-01..2023-07-04"
"queryString": "created:07/01/2023..07/04/2023"
"queryString": "created>=2023-07-01 AND created<=2023-07-03"
"queryString": "created>=07/01/2023 AND created<=07/04/2023"

Instead of the date and time, you can use one of the keywords reserved for the date interval:

  • today - the time from the beginning of the current day until the end of the current day
  • yesterday - the time from the beginning of the day until the end of the day that precedes the current day
  • this week - the time from the beginning of the current week until the end of the current week
  • last week - the entire week that precedes the current week
  • this month - the time from the beginning of the current month until the end of the current month
  • last month - the entire month that precedes the current month
  • this year - the time from the beginning of the current year until the end of the current year
  • last year - the entire year that precedes the current year
"queryString": "created:today"
"queryString": "created:yesterday"
"queryString": "created:\"this week\""
"queryString": "created:\"last week\""
"queryString": "created:\"this month\""
"queryString": "created:\"last month\""
"queryString": "created:\"this year\""
"queryString": "created:\"last year\""

Keyword lastModifiedTime

The same datetime format and reserved keywords as for created.

"queryString": "lastModifiedTime:2023-07-01..2023-07-04"
"queryString": "lastModifiedTime:07/01/2023..07/04/2023"
"queryString": "lastModifiedTime>=2023-07-01 AND lastModifiedTime<=2023-07-03"
"queryString": "lastModifiedTime>=07/01/2023 AND lastModifiedTime<=07/04/2023"
"queryString": "lastModifiedTime:today"
"queryString": "lastModifiedTime:yesterday"
"queryString": "lastModifiedTime:\"this week\""
"queryString": "lastModifiedTime:\"last week\""
"queryString": "lastModifiedTime:\"this month\""
"queryString": "lastModifiedTime:\"last month\""
"queryString": "lastModifiedTime:\"this year\""
"queryString": "lastModifiedTime:\"last year\""

Tips

If you want to search for all sites

POST https://graph.microsoft.com/v1.0/search/query
Content-Type: application/json

{
    "requests": [
        {
            "entityTypes": [
                "site"
            ],
            "query": {
                "queryString": "site:\"https://contoso.sharepoint.com/sites/*\""
            },
            "size": 500
        }
    ]
}

Search for all personal sites

POST https://graph.microsoft.com/v1.0/search/query
Content-Type: application/json

{
    "requests": [
        {
            "entityTypes": [
                "site"
            ],
            "query": {
                "queryString": "site:\"https://contoso-my.sharepoint.com/personal/*\""
            },
            "size": 500
        }
    ]
}

Conclusion

The /search/query endpoint provides better searching than the /sites?$search="xxx" endpoint.

With reserved keywords, the search response will contain more precise results.

0
Buy Me a Coffee at ko-fi.com
An error has occurred. This application may no longer respond until reloaded. Reload x