From time to time you need to search for a SharePoint site. In these days, you have two options with the Graph API:
- the
/sites?search={query}endpoint - the Microsoft Search 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
Default search
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.
