Content Search API

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, namely ContentType. To filter in other collections on all properties, such as by Category 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.