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
Language
Click Try It! to start a request and see the response here!