openapi: 3.2.0
info:
title: Acoustic Delivery context search API
version: 1.0.142
x-ibm-name: ibm-watson-content-hub-api
description: 'Operations tagged Delivery context search across 2 of this provider''s published API definitions: acoustic-content-openapi-original.json, acoustic-content-swagger2-original.yaml. Each path carries the servers of the definition it was published in.'
tags:
- name: Delivery context search
description: "The Delivery context search is a discretional middleware service that is positioned before the Search service. Use the Delivery context search Rest APIs to retrieve user targeted content items. You can target specific content items by providing the condition requests as filters. The filters that are currently supported by the API are \n1. `accept-language` : Use this filter to target content items in a language of your preference. \n2. `location` : Use this filter to target content items that are available in a location, that is, proximity to current location (within `distance` radius) of your preference.\n3. `similar` : Use this filter to target content items or assets that are similar to a specified item.\n"
paths:
/delivery/v1/contextualsearch:
get:
tags:
- Delivery context search
x-ibm-dx-security-user-roles:
- admin
- manager
- editor
- viewer
- authenticatedVisitor
- anonymous
summary: Retrieve contextual search results from the delivery collection
description: "Use the /delivery/v1/contextualsearch endpoint to retrieve contextual search results from the delivery collection based on the passed filters.\nSee the Delivery Search documents on the Content API for details of the main search service parameters.\n#### Current filters\n* `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.\n* `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.\n* `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.\n#### Examples\n* **Search by proximity by using user's location:** \n`q`=type:article&`fl`=description&`filter`=proximity&`distance`=50 \nSearches all content of the type `article` and returns items that are found within 50 km of user's location.\n\n\n* **Search by proximity by providing a location:** \n`q`=type:article&`fl`=description&`filter`=proximity&`distance`=50&`position`=37.25,-5.796 \nSearches 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.\n\n\n* **Search by language (setting the `accept-language` request header):** \n`q`=type:article&`fl`=description&`filter`=accept-language \n`accept-language` de \nSearches all content of the type `article` and returns items where the language is set to `German [de]`.\n\n\n* **Search by language with ordered language list (setting the `accept-language` request header):** \n`q`=type:article&`fl`=description&`filter`=accept-language \n`accept-language` en,de;q=0.5 \nSearches all content of the type 'article` and returns items where the language is set to `English [en]`. Then, proceeds to search all content of the type `article` for `German [de]` if no content is found for `English`.\n\n\n* **Search for images similar to a specified image:** \n`q`=\\*:\\*&`filter`=similar&`similar-source-id`=acd-23-564-09-asdf&`similar-source-classification`=asset&fq=assetType:image&rows=100 \nThe 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.\n\n\n* **Search for images similar to a specified image and sort results in ascending `score` order:** \n`q`=\\*:\\*&`filter`=similar&`similar-source-id`=acd-23-564-09-asdf&`similar-source-classification`=asset&sort=score asc&fq=assetType:image&rows=100 \nThe 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.\n\n\n* **Search for images similar to a specified image and sort results in ascending `lastModified` order:** \n`q`=\\*:\\*&`filter`=similar&`similar-source-id`=acd-23-564-09-asdf&`similar-source-classification`=asset&sort=lastModified asc&fq=assetType:image&rows=100 \nThe 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.\n\n\n* **Apply location and language filters (setting the `accept-language` request header):** \n`q`=type:article&`fl`=description&`filter`=proximity&`filter`=accept-language&`position`=0,0 \n`accept-language` en,de;q=0.5 \nSearches 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.\n\n\n* **Apply similar, location, and language filters (setting the `accept-language` request header):** \n`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 \n`accept-language` en \nThe search returns any type of content which meets all of the following criteria: \n 1. `location` is within a radius of 5 km around the coordinates 0-degrees latitude and 0-degrees longitude \n 2. language is set to `English [de]` \n 3. similar to the item with specified id (`similar-source-id`) and classification (`similar-source-classification`). \n
User roles: admin, manager, editor, viewer, authenticatedVisitor, anonymous"
parameters:
- name: filter
in: query
description: Use the filter parameter to specify the type of contextual filters to apply, it can be used multiple times to apply multiple filters.
required: false
schema:
type: string
format: string
- name: position
description: Provide the center point for a proximity search by using the format "latitude,longitude".
in: query
required: false
schema:
type: string
- name: distance
in: query
description: Provide the value for distance that specifies the bounding radius around the location. The default value is 5.
required: false
schema:
type: number
format: double
default: 5
- name: metric
in: query
description: 'Provide the metric that is used for the distance value.
Acceptable values are km (kilometers) and mi (miles).
The default value is km.
'
required: false
schema:
type: string
format: string
default: km
- name: accept-language
in: header
description: "Provide the ordered list of preferred languages in the request to filter the retrieved search results. \nThis header must be provided if the filter to be applied is `accept-language` (a web browser would provide this header by default).\n"
required: false
schema:
type: string
format: string
- name: similar-source-id
in: query
description: "Provide the ID (uuid) of the item on which to base the `similar` search. \nThis parameter is required if the filter to be applied is `similar`.\n"
required: false
schema:
type: string
format: string
- name: similar-source-classification
in: query
description: "Provide the classification of the item on which to base the `similar` search. \nFor example, to specify an asset classification, use \"asset\". \nThis parameter is required if the filter to be applied is `similar`.\n"
required: false
schema:
type: string
format: string
- name: df
description: Either the Solr "df" or "qf" parameter is required. The parameter is supported by the edismax query parser.
in: query
required: false
schema:
type: string
- name: defType
description: The Solr "defType" parameter. Specify defType=edismax to use the edismax query parser.
in: query
required: false
schema:
type: string
- name: facet
description: The Solr "facet" parameter enables faceted search. Always set this parameter to true if you are using the other "facet" parameters.
in: query
required: false
schema:
type: string
- name: facet.contains
description: The Solr "facet.contains" parameter returns only facets that contain this term.
in: query
required: false
schema:
type: string
- name: facet.containsIgnoreCase
description: The Solr "facet.containsIgnoreCase" parameter ignores case when the "facet.contains" parameter is applied.
in: query
required: false
schema:
type: string
- name: facet.field
description: The Solr "facet.field" parameter identifies a field to be used as a facet.
in: query
required: false
schema:
type: string
- name: facet.limit
description: The Solr "facet.limit" parameter specifies a limit for the number of results that are returned for each facet. Default value is 100.
in: query
required: false
schema:
type: string
- name: facet.offset
description: 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.
in: query
required: false
schema:
type: string
- name: facet.prefix
description: The Solr "facet.prefix" parameter returns only facets with this prefix.
in: query
required: false
schema:
type: string
- name: facet.range
description: The Solr "facet.range" parameter.
in: query
required: false
schema:
type: string
- name: facet.range.gap
description: The Solr "facet.range.gap" parameter.
in: query
required: false
schema:
type: string
- name: facet.range.start
description: The Solr "facet.range.start" parameter.
in: query
required: false
schema:
type: string
- name: facet.range.end
description: The Solr "facet.range.end" parameter.
in: query
required: false
schema:
type: string
- name: fl
description: The Solr "fl" parameter defines the fields that are returned in the response. By default, the search service returns all fields.
in: query
required: false
schema:
type: string
- name: fq
description: The Solr "fq" parameter applies a filter query to the search results.
in: query
required: false
schema:
type: string
- name: f..
description: 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".
in: query
required: false
schema:
type: string
- name: indent
description: 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.
in: query
required: false
schema:
type: string
- name: q
description: The Solr "q" parameter uses Solr/Lucene standard query syntax.
in: query
required: true
schema:
type: string
- name: qf
description: The Solr "qf" parameter is supported by the dismax or edismax query parser.
in: query
required: false
schema:
type: string
- name: rows
description: 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.
in: query
required: false
schema:
type: integer
- name: start
description: 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.
in: query
required: false
schema:
type: integer
- name: sort
description: 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.
in: query
required: false
schema:
type: string
responses:
'200':
description: Successfully returns the results from the delivery search service after it transforms the query based on the passed filters.
headers:
content-language:
description: 'The language of the returned search results when the accept-language filter is used.
This header is not present if no results are found for any of the languages listed in the accept-language header.
'
schema:
type: string
content:
application/json:
schema:
type: object
properties:
query:
type: string
examples:
response:
value:
response:
numFound: 359
documents:
- id: '21'
type: article
title: esse anim mollit
description: Commodo excepteur commodo velit aliqua sunt proident mollit.
owner: Harrell Stanton
locale: en_GB
locations:
- -133.250593
- -19.598289
city: Savannah
country: Germany
demographic: teenager
device: desktop
creationDate: '2001-06-09T15:07:30.000Z'
lastModifiedDate: '2001-06-09T15:07:30.000Z'
_version_: '1537298216475688960'
'400':
description: Bad request - Unable to complete your request due to missing parameters. Provide all required parameters and try again.
content:
application/json:
schema:
title: ErrorMessage
description: ErrorMessage
type: object
properties:
service:
type: string
description: Service name.
requestId:
type: string
description: Request ID.
errors:
type: object
description: Error
title: Error
properties:
code:
type: integer
message:
type: string
level:
type: string
description:
type: string
cause:
type: object
properties:
code:
type: integer
message:
type: string
locale:
type: string
examples:
response:
value:
service: prod-contextual-content-service
requestId: '1983000440420008'
errors:
code: 101
message: Error running query.
level: ERROR
description: Unable to complete the query due to an unexpected error. Try again or contact Acoustic support if problem persists.
locale: en
'429':
description: Too Many Requests, the server has reached a limit, the request must be sent again at a later time.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
default:
description: Unable to complete your request due to an unexpected error. Try again later.
content:
application/json:
schema:
title: ErrorMessage
description: ErrorMessage
type: object
properties:
service:
type: string
description: Service name.
requestId:
type: string
description: Request ID.
errors:
type: object
description: Error
title: Error
properties:
code:
type: integer
message:
type: string
level:
type: string
description:
type: string
cause:
type: object
properties:
code:
type: integer
message:
type: string
locale:
type: string
examples:
response:
value:
service: prod-contextual-content-service
requestId: '455478465455511'
errors:
code: 5004
message: Unexpected error occurred.
level: ERROR
description: Unable to complete the request due to an unexpected error. Try again or contact Acoustic support if problem persists.
locale: en
components:
schemas:
ErrorResponse:
description: This JSON record represents an error condition.
type: object
properties:
errors:
type: array
items:
description: This JSON record represents an individual error or warning contained in an error message.
type: object
properties:
code:
type: integer
description: An error code
message:
type: string
description: A message describing what went wrong.
description:
type: string
description: Further explanation of the error condition and potential next steps to resolve the problem.
more_info:
type: string
description: A URL pointing to a web site that provides more information on the given error condition.
level:
type: string
enum:
- ERROR
- WARNING
description: The severity level of the message. Default is error.
parameters:
type: object
description: Additional properties reflecting the dynamic parts of the error condition.
cause:
type: object
description: This property can be used to transport causing error message records produced by a down stream service calls.
locale:
type: string
description: This property represents the locale of the text contained in properties 'message', and 'description'. This property is mandatory if message and description contain translated text.
required:
- code
- message
requestId:
type: string
description: The ID of the failing request.
service:
type: string
description: The name of the service serving the error message.
required:
- errors
- requestId
x-refined-from:
- acoustic-content-openapi-original.json
- acoustic-content-swagger2-original.yaml
x-readme:
explorer-enabled: true
proxy-enabled: true