Content Search API
Describes the Content Search API's main features and usage.
The Content Search API exposes the ability to query for content in Optimizely Search & Navigation, providing robust filtering and sorting via OData syntax, with support for personalization, proper access control, and a feature for loading referenced content in the same request.
For a complete list of valid endpoints and query parameters, see the Content Delivery API SDK.
Note
The Content Search API adds some properties and data filter to communicate to Optimizely Search & Navigation index. So after installing the Content Search API, you need to re-index your site before start using it to retrieve content.
Install
To use Content Search API endpoints to query contents in your site, install EPiServer.ContentDeliveryApi.Search. After that, register the API in your Startup.cs:
services.AddContentSearchApi(o =>
{
o.MaximumSearchResults = 10;
});
Localize
You can retrieve content in one or more languages within the same request to the Content Search API endpoint. To indicate the desired languages of content to return, attach the Accept-Language header to your request. If you wish to receive content in all languages, pass an empty Accept-Language header or pass a wildcard "*" value.
Accept-Language : en
Accept-Language : en, sv
Accept-Language : en-US,fr-CA
Accept-Language : *
Access control
The Content Search API only returns published content that the current user has access to view.
Users can authorize via Cookie or OpenID using the EPiServer.OpenIDConnect package. See API authentication.
Personalize
The Content Search API leverages indexed data within Optimizely Search & Navigation to deliver search results. By default, personalized contents are not indexed, hence are not returned by Content Search API. To retrieve personalized content (based on the current user and context), pass the personalize query string parameter as true:
?personalize=true
Free text search
The Content Search API endpoint lets callers pass in a free text query, which is evaluated by Optimizely Search & Navigation.
?query=apples
Filter
You can filter search results using the OData v4 filter syntax, providing a capability to write queries to filter down to specific subsets of content.
You can pass OData filters in the filter query string, with support for the following operators and functions:
- Logical Operators – eq, ne, ge, gt, le, lt, and, or
- String Functions – tolower, contains
- Collection Functions – any (Limited support - see Filter by Content Type below)
For information on OData v4 syntax, see URL Conventions for OData v4.
Filter by Content Type
Content can be filtered by a specific content type name, or by the following set of base types: Page, Block, Media, Image, Video.
?filter=ContentType/any(t:t eq 'Page')
?filter=ContentType/any(t:t eq 'ArticlePage')
?filter=ContentType/any(t:t eq 'ArticlePage') or ContentType/any(t:t eq 'CategoryPage')
?filter=ContentType/any(t:t ne 'Block')
Note
The any function support is limited to matching single property expressions on built-in simple
Collection
properties, namelyContentType
. To filter in other collections on all properties, such as byCategory
or by your own Content Area properties, use eq and ne filters (See Filter by Category, Filter by Content Reference, and Filter by Content Area Value below).
When using any
function, you must use the Pascal Case for property name (for example, ContentType, NOT contentType). This is because any function use the property name in filter string to find correct property in C# model class. If you pass a Camel Case property name like contentType, the OData parser throws a parse exception. When working with other functions and operations, use Camel Case with a property name.
Filter by Category
?filter=category/value/id eq 2
?filter=category/value/name eq 'Category Name'
Filter by Content Reference
?filter=contentLink/id eq 6
?filter=contentLink/id ne 6
?filter=contentLink/id ge 10
Filter by Content Area Value
?filter=contentAreaProperty/value/contentLink/id eq 17
?filter=contentAreaProperty/value/contentLink/id ne 4
Filter by Date Range
?filter=startPublish ge 2016-01-01T00:00:00Z and startPublish le 2017-01-01T00:00:00Z
?filter=startPublish ge 2016-01-01T00:00:00Z and startPublish le 2017-01-01T00:00:00Z
Filtering with String Matching
?filter=tolower(name) eq 'start'
?filter=contains(mainBody/value, 'Start')
?filter=contains(tolower(mainBody/value), 'bees')
Order
You can order search results using the OData v4 orderby syntax, with support for multiple sorting criteria.
Orderby expressions are passed in the orderby query string, with support for indicating sort direction with asc and desc descriptors. If a sort direction is not included when passing an orderby string, the direction is defaulted to Ascending.
If the orderby string is excluded or empty, search results are ordered by relevance.
For more information on OData v4 syntax, see URL Conventions for OData v4.
Order by Name
?orderby=name
Order by Recently Changed
?orderby=changed desc
Order by multiple properties
?orderby=name asc, changed desc
Top/skip
Use the top and skip parameters to paginate through search results returned from the Content Delivery API search endpoint. Use the totalMatching
property of the search response to calculate the total number of pages.
?top=10&skip=10
Expand
Use the expand parameter to return data from reference properties in the same request.
?expand=myContentReference
?expand=myContentReference,myContentArea
?expand=*
By default, you can expand the following property types:
- Content Area
- Content Reference
- Content Reference List
- Link Collection
When reference properties are expanded, the full object for the referenced IContent
instances are returned in the response on the expandedValue
property of that property's object.
Expanded properties are fully compatible with the personalize parameter, meaning that only anonymous content is returned when a given property is expanded and personalize is set to false.
Properties on objects that are returned in the ExpandedValue
cannot be expanded further in the same request.
Example request/response
See Search & Navigation APIs and libraries for the detailed Rest API SDK of Content Search API.
Updated 9 months ago