What is the Bloomreach Discovery API?
The Bloomreach Discovery API is a comprehensive REST-based solution that enables developers to integrate advanced product search, personalized recommendations, and merchandising capabilities into e-commerce platforms. These APIs provide a convenient way to interact with Bloomreach Discovery modules through simple HTTP methods, returning responses in JSON format. The Discovery API serves as the foundational layer for powering product discovery experiences, enabling businesses to deliver precisely tailored search results and recommendations that directly influence customer engagement and conversion rates. By leveraging the Discovery API, organizations can programmatically control every aspect of the search and merchandising experience, from query processing to result ranking and personalization.
Core API Categories and Their Functions
Bloomreach Discovery provides multiple API categories, each serving distinct purposes within the product discovery ecosystem. The Catalog Management APIs enable organizations to send product catalog data to Bloomreach and configure catalog settings, establishing the foundation for all subsequent search and recommendation operations. The Search and Merchandising APIs allow developers to implement product search functionality, including autosuggest capabilities that enhance user experience with real-time query suggestions. The Recommendations and Pathways APIs power recommendation widgets such as Frequently Bought Together, New Arrivals, and Bestsellers, enabling dynamic product discovery that increases average order value. The Pixel API facilitates event tracking in non-JavaScript environments, while SEO APIs provide product data for creating thematic pages and optimizing link structures. Each category operates independently while maintaining integration with the broader Bloomreach ecosystem, allowing organizations to implement solutions incrementally based on their specific requirements.
Authentication Mechanisms and Security
Authentication in Bloomreach Discovery varies by API type, with each category employing different security protocols to protect your account and data. The Catalog Management APIs require an API key sent in the Authorization header as a Bearer token, making this authentication mandatory for all catalog-related requests. The Search and Merchandising APIs use an authentication key (distinct from the API key) passed as the auth_key query parameter, though this is only required if your account is configured for authentication during integration. The Recommendations and Pathways APIs do not require any authentication keys since these are typically client-side calls that use only your Bloomreach account ID. The SEO APIs mandate the authentication key in the auth_key parameter for all requests since these are server-side operations. A critical security practice involves sending your private auth_key only for server-side requests and passing an empty value for client-side calls, protecting your account from unauthorized access. This tiered authentication approach balances security with ease of implementation, allowing different teams to access appropriate API functionality without exposing sensitive credentials.
| API Category | API Key in Header | Auth Key Parameter | Mandatory | Use Case |
|---|---|---|---|---|
| Catalog Management | ✅ Yes | ❌ No | ✅ Yes | Product catalog uploads and configuration |
| Search & Merchandising | ❌ No | ✅ Yes (conditional) | ❌ No | Search queries and autosuggest |
| Recommendations & Pathways | ❌ No | ❌ No | ❌ No | Product recommendations and widgets |
| SEO APIs | ❌ No | ✅ Yes | ✅ Yes | Thematic pages and link optimization |
| Pixel API | ❌ No | ❌ No | ❌ No | Event tracking in non-JS environments |
Essential API Endpoints and Request Structure
The Bloomreach Discovery API operates across two distinct environments: staging for integration and testing, and production for live traffic serving. The staging endpoint is https://staging-core.dxpapi.com/api/v1/core/? while the production endpoint is https://core.dxpapi.com/api/v1/core/?. Both endpoints accept identical request formats and parameters, enabling seamless migration from testing to production environments. The Product Search API processes keyword-based product searches with the request type set to search and search type set to keyword, returning matching products with customizable field selection. The Category Search API retrieves products within specific categories using a category ID in the query parameter, with the search type set to category. The Autosuggest API provides real-time query suggestions as users type, enhancing search experience and reducing time to purchase. Each endpoint supports pagination through start and rows parameters, field selection via the fl parameter, faceted filtering for refined results, and result ranking customization. The API enforces a query parameter maximum length of 300 characters and a maximum word count of 30 to ensure optimal performance and prevent abuse.
Step-by-Step Integration Process
Bloomreach provides a structured five-phase integration roadmap that guides organizations from initial planning through successful production deployment. The first phase, Prepare Technical Plan and Design, involves provisioning your product instance and establishing technical requirements with your Bloomreach representative. This phase ensures your infrastructure aligns with Bloomreach’s specifications and that API credentials are properly configured. The second phase, Connect and Configure Catalog, focuses on connecting your product data and customizing the search experience through both API calls and the Bloomreach dashboard. During this phase, you upload your complete product catalog using Catalog Management APIs and configure search rules, merchandising rules, and ranking algorithms. The third phase, Build Site Experience and Send Events, involves deploying the Discovery APIs on your website, implementing event tracking via the Pixel API or direct API calls, and creating the frontend search interface. The fourth phase, Tune and Test Search Experience, emphasizes testing search relevance, fine-tuning ranking algorithms, and validating that results meet business objectives before production deployment. The final phase, Launch Discovery Implementation, moves your configuration to production endpoints and monitors performance metrics to ensure successful operation. This structured approach minimizes implementation risk and ensures that all stakeholders understand their responsibilities at each stage.
Product Search Implementation Example
A typical product search request demonstrates the essential parameters required for successful API integration. The request must include your account_id (provided by Bloomreach), the auth_key for authentication, and a domain_key that identifies your specific domain within Bloomreach’s system. The request_type must be set to search and search_type to keyword for product searches. The q parameter contains the actual search query, such as “dresses” or “running shoes,” while the fl parameter specifies which product fields to return in the response, such as pid, title, brand, price, sale_price, thumb_image, url, and description. The rows parameter controls how many results to return per request (typically 10-20), and the start parameter enables pagination by specifying the offset. The ref_url and url parameters help Bloomreach understand the context of the search request, improving analytics and personalization accuracy. The _br_uid_2 parameter contains a unique user identifier that enables personalization and tracking across sessions. A properly formatted request returns a JSON response containing matching products, facet counts for filtering, and metadata about the search results.
Handling Special Characters and Query Optimization
The Bloomreach Discovery API implements specific rules for handling special characters in search queries to maintain performance and prevent security issues. The asterisk (*) is permitted in search queries and enables wildcard searches, though queries consisting only of asterisks may have higher latency depending on your catalog size. The period (.) is allowed in queries for matching product specifications or model numbers. However, the question mark (?) and tilde (~) characters are not permitted and will trigger a query rewrite that removes these characters from the search string. When multiple special characters appear in a query, such as term1*term2 or term1?term2, the API automatically rewrites the query to remove problematic characters, returning term1 term2 instead. Empty query parameters (q="") and missing query parameters trigger a 400 error response, requiring developers to implement validation to ensure queries are never empty. Understanding these rules prevents unexpected behavior and ensures consistent search results across different query types. When using wildcard queries with asterisks, be aware that merchandising operations such as boost, bury, and slots do not apply to the wildcard results, potentially affecting your carefully configured merchandising rules.
Advanced Features and Response Formats
The Bloomreach Discovery API supports advanced features that enable sophisticated product discovery experiences beyond basic search functionality. Faceted navigation allows customers to refine search results by product attributes such as brand, price range, color, and size, with the API returning facet counts that indicate how many products match each filter option. The latest facet response format (v3) provides unified ranking capabilities that intelligently order facets based on relevance and user interaction patterns. Merchandising operations enable merchandisers to influence search results through boost and bury operations that increase or decrease the visibility of specific products, as well as slot operations that pin products to specific positions in result sets. Field selection via the fl parameter allows developers to request only necessary fields, reducing response payload size and improving API response times. Result sorting can be customized to order products by relevance (default), price, popularity, newest arrivals, or custom fields defined in your product catalog. Pagination support enables efficient browsing of large result sets without loading entire catalogs into memory. Request IDs help track individual requests through Bloomreach’s systems for debugging and performance analysis. These advanced features combine to create highly customizable product discovery experiences that adapt to different business requirements and customer preferences.
Performance Optimization and Best Practices
Successful Bloomreach Discovery API implementations require attention to performance optimization and adherence to best practices that maximize reliability and minimize latency. Implement proper caching by storing frequently requested search results and recommendation data at the application level, reducing unnecessary API calls and improving perceived performance for end users. Use field selection strategically by requesting only the product fields necessary for your frontend display, reducing response payload sizes and improving network performance. Leverage pagination correctly by implementing infinite scroll or load-more patterns that fetch results in manageable chunks rather than attempting to load entire result sets at once. Monitor API usage through the API requests dashboard in your Bloomreach account, tracking request volume, response times, and error rates to identify optimization opportunities. Implement error handling that gracefully manages API timeouts, authentication failures, and malformed responses, providing fallback experiences that maintain customer satisfaction even during temporary service disruptions. Use staging extensively before deploying changes to production, testing search queries, merchandising rules, and API configurations to ensure they deliver expected results. Track search analytics by sending events through the Pixel API or direct API calls, providing Bloomreach with data needed for personalization and enabling your team to understand search performance metrics. Optimize query structure by ensuring search queries are well-formed, avoiding special character issues, and implementing query validation on the client side before sending to the API. These practices collectively ensure that your Bloomreach Discovery implementation delivers reliable, fast, and effective product discovery experiences.
Integration with Voxwise for Maximum Impact
While Bloomreach Discovery APIs provide powerful capabilities, successfully implementing and optimizing these systems requires deep technical expertise and strategic business understanding. Voxwise specializes in helping e-commerce organizations maximize their Bloomreach investments through expert implementation, optimization, and ongoing management services. Our team combines deep API knowledge with proven best practices from hundreds of successful implementations, ensuring your Discovery deployment delivers measurable business results. Voxwise consultants understand not just the technical mechanics of API integration, but how to align search and merchandising strategies with your broader business objectives, competitive positioning, and customer expectations. We guide organizations through every phase of the integration roadmap, from initial planning and architecture design through production deployment and ongoing optimization. Our approach emphasizes measurable outcomes—increased search conversion rates, improved average order value, and enhanced customer satisfaction—rather than simply implementing features. Whether you’re beginning your Bloomreach journey or optimizing an existing implementation, Voxwise provides the strategic guidance and technical expertise needed to transform product discovery into a competitive advantage.
Ready to Optimize Your Product Discovery?
Bloomreach Discovery APIs unlock powerful personalization and search capabilities, but realizing their full potential requires strategic implementation and continuous optimization. The technical complexity of API integration, authentication management, and performance tuning demands expertise that extends beyond documentation and general consulting.
Voxwise is the premier partner for Bloomreach Discovery implementation and optimization. Our consultants combine deep platform expertise with proven strategies for maximizing search conversion, improving merchandising effectiveness, and delivering exceptional customer experiences. We’ve guided leading e-commerce brands through successful Discovery implementations that significantly improved product discoverability and revenue per visitor.
See our services and discover how Voxwise can accelerate your Bloomreach Discovery implementation and drive measurable business results.
Get Expert Advice from our team today and learn how to maximize your product discovery strategy with Bloomreach Discovery APIs.