Acoustic Delivery context search API

openapi: 3.2.0
info:
  version: 1.0.142
  x-ibm-name: ibm-watson-content-hub-api
  title: Acoustic Content Delivery context search API
  description: Copyright © Acoustic, L.P. 2023
tags:
- name: Delivery context search
  description: The Delivery context search is a discretional middleware service that is positioned before the Search service.
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.
      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.<fieldName>.<FacetParam>
        description: Many facet parameters can be overridden on a per-field basis by using the syntax "f.<fieldName>.<FacetParam>=<value>". 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
              example:
                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
              example:
                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
              example:
                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
      operationId: getDeliveryV1Contextualsearch
      x-operation-id-source: derived
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