Retrieve contextual search results from the delivery collection

Use the /delivery/v1/contextualsearch endpoint to retrieve contextual search results from the delivery collection based on the passed filters.
See the Delivery Search documents on the Content API for details of the main search service parameters.

Current filters

  • accept-language Searches for content with matching languages. If this filter is specified the accept-language request header must be specified with the ordered list of languages to search with. The search iterates through all of the languages in order until a language returns one or more matching content items or the service has completed the search for all the languages without finding any results. If the search returns content items the response header content-language is set to the language that returned those content items, otherwise this header is not returned in the response.
  • proximity Searches for content located within a certain radius of a specified location. proximity is used in combination with distance which is the bounding radius around the location. You can specify the location with the position parameter. If the parameter is not provided the location is read from the X-Akamai-Edgescape header. If the distance parameter is not provided distance is defaulted to 5.
  • similar Searches for content or assets that are similar to a specified item. similar uses the tags added by AI, a user, or included in the asset, such as image metadata tags to search. The content and assets with matching tags to the specified item are returned. Based on the number of tags that match a 'score' is calculated for each content and asset, the bigger the number of matching tags the higher the score. The results are returned as an ordered array response that starts with items with the highest score and lists them in a descending order. Note: Since the specified item in the query would be a perfect match, it is not returned as a result.

Examples

  • Search by proximity by using user's location:
    q=type:article&fl=description&filter=proximity&distance=50
    Searches all content of the type article and returns items that are found within 50 km of user's location.

  • Search by proximity by providing a location:
    q=type:article&fl=description&filter=proximity&distance=50&position=37.25,-5.796
    Searches all content of the type article and returns items that are found within 50 km of the location that is specifed in the position parameter.

  • Search by language (setting the accept-language request header):
    q=type:article&fl=description&filter=accept-language
    accept-language de
    Searches all content of the type article and returns items where the language is set to German [de].

  • Search by language with ordered language list (setting the accept-language request header):
    q=type:article&fl=description&filter=accept-language
    accept-language en,de;q=0.5
    Searches all content of the type 'articleand returns items where the language is set toEnglish [en]. Then, proceeds to search all content of the type articleforGerman [de]if no content is found forEnglish`.

  • Search for images similar to a specified image:
    q=*:*&filter=similar&similar-source-id=acd-23-564-09-asdf&similar-source-classification=asset&fq=assetType:image&rows=100
    The search returns images that are similar to the item with the specified ID (similar-source-id) and classification (similar-source-classification). The results are sorted in order of descending score by default.

  • Search for images similar to a specified image and sort results in ascending score order:
    q=*:*&filter=similar&similar-source-id=acd-23-564-09-asdf&similar-source-classification=asset&sort=score asc&fq=assetType:image&rows=100
    The search returns images that are similar to the item with the specified ID (similar-source-id) and classification (similar-source-classification). The results are sorted in order of ascending score.

  • Search for images similar to a specified image and sort results in ascending lastModified order:
    q=*:*&filter=similar&similar-source-id=acd-23-564-09-asdf&similar-source-classification=asset&sort=lastModified asc&fq=assetType:image&rows=100
    The search returns images that are similar to the item with the specified ID (similar-source-id) and classification (similar-source-classification). The results are sorted in order of ascending last modified date.

  • Apply location and language filters (setting the accept-language request header):
    q=type:article&fl=description&filter=proximity&filter=accept-language&position=0,0
    accept-language en,de;q=0.5
    Searches all content of the type article and returns items where the language is set to English [en] and the location is within a 5 km radius around the coordinates 0-degrees latitude and 0-degrees longitude. Then, proceeds to search all content of the type article for German [de] and location within a 5 km radius around the coordinates 0-degrees latitude and 0-degrees longitude if no content is found for English based search.

  • Apply similar, location, and language filters (setting the accept-language request header):
    q=*:*&fl=description&filter=proximity&filter=accept-language&position=0,0&filter=similar&similar-source-id=acd-23-564-09-asdf&similar-source-classification=content&fq=classification:content&rows=100
    accept-language en
    The search returns any type of content which meets all of the following criteria:

    1. location is within a radius of 5 km around the coordinates 0-degrees latitude and 0-degrees longitude
    2. language is set to English [de]
    3. similar to the item with specified id (similar-source-id) and classification (similar-source-classification).

      User roles: admin, manager, editor, viewer, authenticatedVisitor, anonymous
Log in to see full request history
timestatususer agent
Retrieving recent requests…
LoadingLoading…
Query Params
string

Use the filter parameter to specify the type of contextual filters to apply, it can be used multiple times to apply multiple filters.

string

Provide the center point for a proximity search by using the format "latitude,longitude".

double
Defaults to 5

Provide the value for distance that specifies the bounding radius around the location. The default value is 5.

string
Defaults to km

Provide the metric that is used for the distance value.
Acceptable values are km (kilometers) and mi (miles).
The default value is km.

string

Provide the ID (uuid) of the item on which to base the similar search.
This parameter is required if the filter to be applied is similar.

string

Provide the classification of the item on which to base the similar search.
For example, to specify an asset classification, use "asset".
This parameter is required if the filter to be applied is similar.

string

Either the Solr "df" or "qf" parameter is required. The parameter is supported by the edismax query parser.

string

The Solr "defType" parameter. Specify defType=edismax to use the edismax query parser.

string

The Solr "facet" parameter enables faceted search. Always set this parameter to true if you are using the other "facet" parameters.

string

The Solr "facet.contains" parameter returns only facets that contain this term.

string

The Solr "facet.containsIgnoreCase" parameter ignores case when the "facet.contains" parameter is applied.

string

The Solr "facet.field" parameter identifies a field to be used as a facet.

string

The Solr "facet.limit" parameter specifies a limit for the number of results that are returned for each facet. Default value is 100.

string

The Solr "facet.offset" parameter specifies an offset into the facet results that are returned and can be used for paging facet results. Default value is 0.

string

The Solr "facet.prefix" parameter returns only facets with this prefix.

string

The Solr "facet.range" parameter.

string

The Solr "facet.range.gap" parameter.

string

The Solr "facet.range.start" parameter.

string

The Solr "facet.range.end" parameter.

string

The Solr "fl" parameter defines the fields that are returned in the response. By default, the search service returns all fields.

string

The Solr "fq" parameter applies a filter query to the search results.

string

Many facet parameters can be overridden on a per-field basis by using the syntax "f..=". For example, to specify a general limit of 10 terms for all facet fields and a specific limit of five terms for only the "category" facet field, use "facet.limit=10" and "f.category.facet.limit=5".

string

If the Solr "indent" parameter is not "off" and has a non-blank value, then Solr attempts to indent the XML response such that it is easier to read. The default behavior is not to indent the XML response.

string
required

The Solr "q" parameter uses Solr/Lucene standard query syntax.

string

The Solr "qf" parameter is supported by the dismax or edismax query parser.

integer

The Solr "rows" parameter controls how many documents are returned at the most, and can be used for paging query results. The default value is 10. The maximum allowed value is 1000.

integer

The Solr "start" parameter specifies an offset into the responses which are returned and can be used for paging query results. Default value is 0.

string

The Solr "sort" parameter controls sorting of the query response. Sorting on not unique fields can cause paging to return duplicate or missing entries in subsequent pages of results. It's recommended to sort by unique field or a combination ex. sort=lastModied desc, status desc.

Headers
string

Provide the ordered list of preferred languages in the request to filter the retrieved search results.
This header must be provided if the filter to be applied is accept-language (a web browser would provide this header by default).

Responses

Language
Click Try It! to start a request and see the response here! Or choose an example:
application/json