openapi: 3.0.0
info:
  title: Product and Category Search API
  version: "1.0"
paths:
  /:
    get:
      tags: [Product & Category Search API v1]
      summary: Get products/categories
      description:
        The <b>Product Search API</b> sends a keyword query to retrieve results about products and other content on your site. You can apply additional filters and facets to return products and content that either include or exclude specified attributes like colors and brands.
        The <b>Category Search API</b> sends a category query to retrieve results about products within the categories that you specify.
      operationId: product-category-search-api
      parameters:
        - name: _br_uid_2
          in: query
          description:
            A first-party cookie created by the Bloomreach tracking pixel
            library (BrTrk). This cookie creates a unique, anonymous identifier
            for every browser or device. <br><br> Use the default value
            provided, which is already encoded.
          required: true
          example: "{{ br_uid_2 }}"
          schema:
            type: string
            default: uid%3D7797686432023%3Av%3D11.5%3Ats%3D1428617911187%3Ahc%3D55
        - name: account_id
          in: query
          description:
            Your site's numerical Bloomreach account ID. Your Bloomreach
            representative gives your site's account ID to you before or during
            your integration kickoff meeting. <br><br> The example value shown
            here, <i>6702</i>, is included for your convenience to send a
            request with <b>Try It</b>. </br> <div
            background-color="red>Callout</div>
          required: true
          example: "{{ account_id }}"
          schema:
            type: integer
            format: int32
            default: 6370
        - name: auth_key
          in: query
          description:
            The Bloomreach-provided authentication key for the Bloomreach
            account that's sending the request. <br><br> Pass the auth_key with
            an empty value in client-side calls.  The auth_key value is a
            private authorization key. If you include your valid auth_key value
            in client-side calls, then you inadvertently expose that private
            information to everybody.
          example: "{{ auth_key }}"
          schema:
            type: string
        - name: domain_key
          in: query
          description:
            Your site domain's ID, which is provided by Bloomreach. This ID is
            for the domain that you want to receive your Bloomreach API
            requests.  This parameter identifies the specific site version when
            the one account ID hosts multiple site versions with unique
            characteristics, such as language versions. Bloomreach uses your
            domain_key parameter value to ensure that only the data that
            pertains to that site version is used for query and analytics
            features, such as autosuggestions. <br><br> The example value shown
            here, <i>documentation_site</i>, is included for your convenience to
            send a request with <b>Try It</b>.
          required: true
          example: "{{ domain_key }}"
          schema:
            type: string
            default: documentation_site
        - name: ref_url
          in: query
          description:
            The URL of the page or HTTP referrer where the request is started.
          required: true
          example: "{{ ref_url }}"
          schema:
            type: string
        - name: request_type
          in: query
          description:
            The type of API request. Value should be **search** for Product
            Search or Category requests.
          required: true
          example: search
          schema:
            type: string
            enum:
              - search
            default: search
        - name: search_type
          in: query
          description:
            The type of search. Value should be **keyword** for Product Search
            requests, **category** for Category requests.
          required: true
          example: keyword
          schema:
            type: string
            enum:
              - keyword
              - category
            default: keyword
        - name: callback
          in: query
          description:
            Indicates whether to return data wrapped in the function for
            cross-origin requests.  <br><br> For server-side requests, use the
            value **br_server**. For native-app requests, use the value
            **br_app**.
          schema:
            type: string
            enum:
              - br_server
              - br_app
        - name: efq
          in: query
          description:
            Applies a complex boolean filter to search results to include or
            exclude items that fit your parameter values. Any product attribute
            in your product feed is valid, such as brand names and sizes.
            <br><br> Typically, the efq parameter is used for custom attributes
            that you include in your product feed to support additional business
            logic that you might need to filter.  Read more about using the efq
            parameter in the "Complex boolean filtering" section in the
            [Faceting and filtering page](ref:faceting-and-filtering).
          schema:
            type: string
        - name: br_diagnostics
          in: query
          description:
            "This parameter sends Product grid insights data in the API response
            to help debug your search results.<br>Allowed values are:
            `all`/`recall`/`ranking`/`merchandising`.<br><br>Refer to the guide
            [Product grid insights on the API](https://documentation.bloomreach.com/discovery/reference/ranking-diagnostics-on-the-api)
            for more details, like the response format."
          example: all
          schema:
            type: string
            enum:
              - all
              - recall
              - ranking
              - merchandising
        - name: facet.range
          in: query
          description:
            Return a count of ranged facets, such as price and sale price. Use
            numeric attributes only. <br><br> You need to parse the values that
            are in the facets_counts section of the response. The facet_queries
            section has custom range facets for numeric fields that you define
            in your request. The facet_fields section gives you facets that you
            can display to your site's users, such as brands and colors.
          schema:
            type: string
        - name: facet.version
          in: query
          description:
            Set the value of this parameter to "3.0" to use the new [Facet
            Response
            v3](https://documentation.bloomreach.com/discovery/reference/facet-response-v3-unified-ranking).
            This will return the facet information in the new unified format.
          example: "3.0"
          schema:
            type: number
            format: float
        - name: fl
          in: query
          description:
            The attributes that you want returned in your API response, such as
            product IDs and prices. <br><br> All fl parameters for Product
            Search or Category requests must include **pid** as one of their
            values. Any attribute from your product feed may be used as a value
            for fl. <br><br> Multiple values should be comma separated, such as
            **fl=pid,price**.
          required: true
          example: pid,url,description
          schema:
            type: string
            default: pid,url,description
        - name: fq
          in: query
          description:
            The fq parameter applies a faceted filter to the returned products,
            searching for products that fit your parameter values. <br><br> Any
            facet that you want to filter must be in your feed.  Read more about
            using the fq parameter in the "Simple Filtering" section in the
            [Faceting and filtering page](ref:faceting-and-filtering). <br><br>
            You can [configure Attributes](doc:understanding-feed-configuring-attributes)
            from the Catalog Management Tab. Configure which attributes in your
            content feed you want to apply as filters to search results.   
          schema:
            type: string
        - name: ll
          in: query
          description:
            The latitude-longitude of the end-customer used for the [Buy Online
            Pick-up In Store (BOPIS)
            feature](doc:buy-online-pick-up-in-store-bopis). <br><br> Value
            should be provided as latitude,longitude. For example,
            **ll=11.09,10.018**. <br><br> Use **fl=store_lat_lon** to return the
            distance from ll. In the response body, this value is returned as an
            additional field with the suffix ‘.distance’. <br><br> Use
            **fq=store_lat_lon** to enable filtering by distance.
          example: "11.09,10.018"
          schema:
            type: string
        - name: merchandising.ts
          in: query
          description:
            "This parameter allows you to preview the search results that would
            be produced at a future date.<br>It takes all the merchandising
            rules that will be active at the entered timestamp into
            account.<br>Example (Unix Epoch timestamp): 1703497216<br><br>If you
            have scheduled rules through the [duration selector in the
            dashboard](https://documentation.bloomreach.com/discovery/docs/product-grid-editor#duration),
            this parameter can help you preview their combined impact up to 21
            days in advance."
          example: "1703497216"
          schema:
            type: string
            format: date-time
        - name: q
          in: query
          description:
            Your site visitor's search query. Search queries are composed of one
            or more terms. <br><br> For Category queries, the value is the
            category ID. <br><br> You can percent encode spaces between terms as
            %20, or you can leave the spaces unencoded.  <br><br> If you use
            q=\*, the latency of the response will vary depending on your
            catalog size and it may not adhere to Bloomreach's standard SLA.
            Additionally, most merchandising operations do not work on \* query
            parameters, except for include/exclude operations. <br><br> The
            example value shown here, <i>cable</i>, is included for your
            convenience to send a request with <b>Try It</b>.
          required: true
          examples:
            product:
              value: cable
              summary: Search terms
            category:
              value: PNB160303000000
              summary: Category ID
          schema:
            type: string
            default: cable
        - name: content_injection
          in: query
          description:
            This parameter enables the [Personalized media in grid](https://documentation.bloomreach.com/discovery/docs/personalized-media-in-the-grid) feature.
            <br>If `true`, the API response includes media objects along with product results. The content and positions
            <br>of the media objects are governed by the [assets and media rules](https://documentation.bloomreach.com/discovery/docs/assets-and-media-rules)
            configured in the Bloomreach dashboard. 
          required: false
          example: true
          schema:
            type: boolean
        - name: request_id
          in: query
          description:
            An ID to track the API request for identification in logs.
            <br><br> Bloomreach doesn't automatically enforce the requirements
            for this parameter. For example, you can enter `test` as your value
            for each instance of the request_id parameter without triggering an
            error message. However, using a unique value (random number/Unix Timestamp) allows us to help you
            if you encounter a problem.
          required: false
          example: 1234567891234
          schema:
            type: string
        - name: rows
          in: query
          description:
            The number of matching items to return per results page in the API
            response. The maximum value is 200.<br><br>To enhance performance,
            limit this value to the number of items that you think is reasonable
            for a single page of search results.
          required: false
          example: 20
          schema:
            type: integer
            format: int32
            default: 20
        - name: sort
          in: query
          description:
            Sorts results based on the field value in ascending, descending, or
            another combination of orders. You can sort any fl field. <br><br>
            Value is a field name, followed by **asc**/**desc** for
            ascending/descending order, respectively. For example,
            **sort=sale_price desc** sorts in descending order of the sale price
          example: sale_price desc
          schema:
            type: string
        - name: start
          in: query
          description:
            The number of the first item on a page of results. For example, the
            first item on the first page is 0, making the start value also 0.
            <br><br> The maximum value is 10000.
          required: false
          example: 0
          schema:
            type: integer
            format: int32
            default: 0
        - name: stats.field
          in: query
          description:
            This parameter allows you to display the maximum and minimum values
            of any numeric field in your data set for a user query. With this
            parameter, you can get all the documents matching a query and
            display the minimum and maximum values of single-valued, numeric
            attributes such as price, sale_price, length, width, reviews, etc.
            <br><br> Values are returned in the response as **stats_field**.
          schema:
            type: string
        - name: url
          in: query
          description:
            The absolute URL of the page where the request is initiated. Do not
            use a relative URL. <br><br> The example value shown here,
            <i>https://www.documentation-site.com</i>, is included for your
            convenience to send a request with <b>Try It</b>.
          required: true
          example: "{{ url }}"
          schema:
            type: string
            default: https://www.documentation-site.com
        - name: user_id
          in: query
          description:
            The universal customer ID of the user. You only need to pass this
            field if your particular integration tracks customers this way.  The
            parameter captures user IDs from the customer side, and reuses the
            information when powering apps or enhancing cross-device linking. In
            this way, Bloomreach recognizes users in a way that's aligned with
            your system. <br><br> Use an anonymous string. Don't use email or
            other personally identifiable information. If you do not track users
            this way, then omit this field.
          schema:
            type: string
        - name: view_id
          in: query
          description:
            A unique identifier for a specific view of your product catalog. If
            you have multiple versions of your site, each with their own product
            catalog characteristics like product titles and prices, then add
            view_id to your call. <br><br> Bloomreach uses your view_id
            parameter value to display the right product information for your
            customers based on their individual site views.  You can enter any
            string value to identify the specific site catalog view. This string
            must be consistent in your pixel, API, and product catalog.
          schema:
            type: string
        - name: widget_id
          in: query
          description:
            The widget_id provided in the Dashboard for the Dynamic Widgets
            feature, which is used to provided curated results. <br><br> This is
            an optional feature that can be enabled by discussing with your CSM.
          schema:
            type: string
      deprecated: false
      responses:
        "200":
          description: Successful response. Click to see response body.
          content:
            "application/json":
              schema:
                $ref: "#/components/schemas/SearchResponse"
components:
  schemas:
    # The main Product data object
    SearchResponseDoc:
      additionalProperties: false
      properties:
        brand:
          type: string
        description:
          type: string
        pid:
          type: string
        price:
          type: number
        price_range:
          type: array
          items:
            type: number
        promotions:
          type: array
          items:
            type: string
        sale_price:
          type: number
        sale_price_range:
          type: array
          items:
            type: number
        score:
          type: number
        thumb_image:
          type: string
        title:
          type: string
        url:
          type: string
        variants:
          type: array
          items:
            $ref: "#/components/schemas/Variant"
      required:
        - sale_price
        - price
        - description
        - title
        - url
        - brand
        - pid
        - thumb_image
        - sale_price_range
        - price_range
        - variants
      type: object
    # Variant for products
    Variant:
      additionalProperties: false
      properties:
        sku_color_group:
          type: string
        sku_price:
          type: number
        sku_sale_price:
          type: number
        sku_swatch_images:
          type: array
          items:
            type: string
        sku_thumb_images:
          type: array
          items:
            type: string
        skuid:
          type: string
      required:
        - sku_color_group
        - sku_swatch_images
        - sku_thumb_images
      type: object
    # Search Response (main)
    SearchResponse:
      additionalProperties: false
      properties:
        response:
          $ref: "#/components/schemas/SearchResponseResponse"
        facet_counts:
          $ref: "#/components/schemas/SearchResponseFacetCounts"
        category_map:
          type: object
        autoCorrectQuery:
          type: string
        did_you_mean:
          type: array
          items:
            type: string
        keywordRedirect:
          $ref: "#/components/schemas/SearchResponseKeywords"
        group_response:
          $ref: "#/components/schemas/SearchResponseGroupResponse"
        stats:
          $ref: "#/components/schemas/SearchResponseStats"
        metadata:
          $ref: "#/components/schemas/SearchResponseMetadata"
      type: object
    # Facet counts for search response
    SearchResponseFacetCounts:
      additionalProperties: false
      properties:
        facets:
          $ref: "#/components/schemas/SearchResponseFacetCountsFacets"  
        facet_fields:
          $ref: "#/components/schemas/SearchResponseFacetCountsFacetFields"
        facet_queries:
          type: object
        facet_ranges:
          $ref: "#/components/schemas/SearchResponseFacetCountsFacetRanges"
      type: object
    SearchResponseFacetCountsFacets:
      type: array
      items:
        type: object
        properties:
          name:
            type: string
            example: AverageRating
          type:
            type: string
            enum: [number, number_range, number_stats, text]
            example: text
          value:
            type: array
            items:
              type: object
              properties:
                name:
                  type: string
                  example: Decent
                count:
                  type: integer
                  example: 15
                start:
                  type: number
                end:
                  type: number  
    SearchResponseFacetCountsFacetFields:
      additionalProperties:
        type: array
        items:
          type: object
      properties:
        category:
          type: array
          items:
            $ref: "#/components/schemas/SearchResponseFacetCountsFacetFieldsCategory"
      type: object
    SearchResponseFacetCountsFacetFieldsCategory:
      additionalProperties: false
      properties:
        cat_id:
          type: string
        cat_name:
          type: string
        count:
          type: number
        crumb:
          type: string
        parent:
          type: string
        tree_path:
          type: string
      type: object
    SearchResponseFacetCountsFacetRanges:
      additionalProperties: false
      properties:
        price:
          type: array
          items:
            $ref: "#/components/schemas/SearchResponseFacetCountsFacetRangesPrice"
      type: object
    SearchResponseFacetCountsFacetRangesPrice:
      additionalProperties: false
      properties:
        count:
          type: number
        end:
          type: number
        start:
          type: number
      required:
        - count
        - start
        - end
      type: object
    SearchResponseGroupResponse:
      additionalProperties:
        $ref: "#/components/schemas/SearchResponseGroupResponseGroupList"
      type: object
    SearchResponseGroupResponseGroupList:
      additionalProperties: false
      required:
        - matches
        - groups
      properties:
        groups:
          type: array
          items:
            $ref: "#/components/schemas/SearchResponseGroupResponseGroupListGroup"
        matches:
          type: number
      type: object
    SearchResponseGroupResponseGroupListGroup:
      additionalProperties: false
      required:
        - groupValue
      properties:
        doclist:
          additionalProperties: false
          properties:
            docs:
              type: array
              items:
                $ref: "#/components/schemas/SearchResponseDoc"
            maxScore:
              type: number
            numFound:
              type: number
            start:
              type: number
          type: object
        groupValue:
          type: string
      type: object
    SearchResponseKeywords:
      additionalProperties: false
      required:
        - original_query
        - redirected_query
        - redirected_url
      properties:
        original_query:
          type: string
        redirected_query:
          type: string
        redirected_url:
          type: string
      type: object
    # Standard search response with docs (products)
    SearchResponseResponse:
      additionalProperties: false
      properties:
        maxScore:
          type: number
        numFound:
          type: number
        start:
          type: number
        docs:
          type: array
          items:
            $ref: "#/components/schemas/SearchResponseDoc"
      type: object
    # Stats/aggregations
    SearchResponseStats:
      additionalProperties: false
      required:
        - stats_fields
      properties:
        stats_fields:
          $ref: "#/components/schemas/SearchResponseStatsStatsFields"
      type: object
    SearchResponseStatsStatsFields:
      additionalProperties: false
      properties:
        price:
          $ref: "#/components/schemas/SearchResponseStatsStatsFieldsPrice"
        sale_price:
          $ref: "#/components/schemas/SearchResponseStatsStatsFieldsPrice"
      type: object
    SearchResponseStatsStatsFieldsPrice:
      additionalProperties: false
      required:
        - max
        - min
      properties:
        max:
          type: number
        min:
          type: number
      type: object
    SearchResponseMetadata:
      type: object
      properties:
        query:
          type: object
          properties:
            query_tags:
              type: object
              properties:
                untagged_tokens:
                  type: array
                  items:
                    type: string
            precision:
              type: object
              properties:
                configured:
                  type: object
                  properties:
                    value:
                      type: string
                applied:
                  type: object
                  properties:
                    value:
                      type: string
        experiments:
          type: array
          items:
            type: object
            properties:
              ab_test_experiment_name:
                type: string
              ab_test_variant_name:
                type: string     
security:
  - {}
servers:
  - url: https://core.dxpapi.com/api/v1/core
x-readme:
  headers: []
  explorer-enabled: true
  proxy-enabled: true
  samples-enabled: true
x-readme-fauxas: true