XTAL Search — Integration Guide
https://xtalsearch.com/docs/integration
Integration Guide
XTAL Search is an AI-powered product search engine for e-commerce. It combines vector similarity search, AI query understanding, and real-time faceting to deliver highly relevant product results.
Architecture
The storefront sends search queries to the XTAL API (hosted at xtalsearch.com), which returns ranked product results with facets and AI-generated aspects.
Quick Start
The fastest way to integrate XTAL Search is via our JavaScript snippet. Add this to your storefront's <head> tag:
<link rel="preconnect" href="https://www.xtalsearch.com">
<script>
(function(){
var s = document.createElement('script');
s.src = 'https://www.xtalsearch.com/client/v1/xtal.js';
s.async = true;
s.dataset.shopId = 'YOUR_COLLECTION_ID';
document.head.appendChild(s);
})();
</script>Replace YOUR_COLLECTION_ID with your assigned collection identifier. The snippet automatically discovers your search input and renders results in an overlay.
Integration Options
XTAL supports two integration approaches. Choose based on your platform's architecture and requirements.
JavaScript Snippet
- Single
<script>tag in storefront head - Zero backend changes required
- Renders results in overlay or inline
- Handles search input interception automatically
- Best for: quick integration, minimal dev effort
Server-Side API
- Your backend calls XTAL REST endpoints
- Render results in your own templates
- Full control over result display and UX
- Better for SEO (server-side rendering)
- Best for: custom UX, SSR, deep platform integration
| Aspect | JS Snippet | Server-Side API |
|---|---|---|
| Implementation effort | Minimal (1 script tag) | Moderate (API + templates) |
| Backend changes | None | Required |
| SEO / SSR | Client-only rendering | Full SSR support |
| UX customization | Configurable via settings | Full control |
| Latency | Direct browser → XTAL | Browser → your server → XTAL |
API Reference
/api/xtal/searchExecute a product search query. Returns ranked results, facets, relevance scores, and search context for subsequent filtering.
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
| query | string | Yes | The search query text |
| limit | number | No | Results per page (default: 48) |
| collection | string | No | Collection identifier (e.g., "willow") |
| search_context | SearchContext | No | Context from a previous search (for filtering) |
| selected_aspects | string[] | No | AI-generated aspect filters to apply |
| facet_filters | Record<string, string[]> | No | Tag-based facet filters (e.g., {"color": ["red"]}) |
| price_range | {min, max} | No | Price filter in dollars (e.g., {"min": 10, "max": 100}) |
Example Request
POST /api/xtal/search
Content-Type: application/json
{
"query": "wireless headphones",
"limit": 24,
"collection": "willow"
}Example Response
{
"results": [
{
"id": "prod_8291",
"title": "Premium Wireless Over-Ear Headphones",
"name": "Premium Wireless Over-Ear Headphones",
"price": 149.99,
"image_url": "https://cdn.example.com/headphones-1.jpg",
"product_url": "https://store.example.com/products/headphones-1",
"vendor": "AudioTech",
"product_type": "Headphones",
"tags": ["category_electronics", "brand_audiotech", "color_black"],
"description": "High-fidelity wireless headphones with ANC...",
"images": [{"src": "https://cdn.example.com/headphones-1.jpg"}],
"variants": [{"price": 149.99, "compare_at_price": 199.99}],
"available": true
}
],
"total": 42,
"query_time": 187,
"relevance_scores": {
"prod_8291": 0.92
},
"search_context": {
"augmented_query": "wireless bluetooth headphones over-ear",
"extracted_price_lte": null,
"extracted_price_gte": null,
"product_keyword": "headphones"
},
"computed_facets": {
"category": {"electronics": 42, "audio": 38},
"brand": {"audiotech": 12, "soundwave": 8},
"color": {"black": 20, "white": 15}
}
}/api/xtal/aspectsGenerate AI-powered search aspects (dynamic facets) for a given query. Aspects are natural-language refinement options like "noise cancelling" or "under $50".
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
| query | string | Yes | The search query text |
| selected_aspects | string[] | No | Previously selected aspects (for context) |
| collection | string | No | Collection identifier |
Example Request
POST /api/xtal/aspects
Content-Type: application/json
{
"query": "wireless headphones",
"collection": "willow"
}Example Response
{
"aspects": [
"noise cancelling",
"over-ear",
"under $100",
"bluetooth 5.0",
"long battery life"
],
"aspects_enabled": true
}/api/xtal/configRetrieve the configuration for a collection. Used by the JS snippet to configure its behavior. Cached for 5 minutes.
Query Parameters
| Field | Type | Required | Description |
|---|---|---|---|
| shopId | string | Yes | Collection identifier (e.g., "willow") |
Example Request
GET /api/xtal/config?shopId=willowExample Response
{
"shopId": "willow",
"enabled": true,
"searchSelector": "input[type=\"search\"]",
"resultsSelector": "",
"displayMode": "overlay",
"resultsPerPage": 48,
"utm": {
"source": "xtal",
"medium": "search",
"campaign": "willow"
},
"features": {
"aspects": true,
"explain": true
}
}Data Models
Product
Each result in the search response is a Product object with the following fields:
| Field | Type | Required | Description |
|---|---|---|---|
| id | string | Yes | Unique product identifier |
| title | string | Yes | Product name |
| name | string | Yes | Alternate name field |
| price | number | number[] | Yes | Price in dollars. Array for price ranges (e.g., variant min/max) |
| image_url | string | null | Yes | Primary product image URL |
| product_url | string | Yes | Link to the product detail page |
| vendor | string | Yes | Brand or manufacturer name |
| product_type | string | Yes | Product category (e.g., "Headphones") |
| tags | string[] | Yes | Metadata tags used for faceting (e.g., ["color_black", "brand_sony"]) |
| description | string | No | Product description text |
| images | Image[] | Yes | Array of {src, alt_text} image objects |
| variants | Variant[] | Yes | Array of {price, compare_at_price} variant objects |
| available | boolean | Yes | Whether the product is in stock |
SearchContext
Returned with initial search results. Pass this back on subsequent requests (filtering, pagination) to avoid re-processing the query.
| Field | Type | Required | Description |
|---|---|---|---|
| augmented_query | string | Yes | AI-enhanced version of the original query |
| extracted_price_lte | number | null | Yes | Extracted max price from natural language (e.g., "under $50" → 50) |
| extracted_price_gte | number | null | Yes | Extracted min price from natural language |
| product_keyword | string | null | No | Extracted product type keyword |
Facets & Filtering
Products are tagged with prefixed metadata (e.g., color_black, brand_sony). The search response groups these into computed_facets, keyed by prefix with value counts:
{
"computed_facets": {
"color": {"black": 20, "white": 15, "red": 8},
"brand": {"sony": 12, "bose": 10, "apple": 7},
"category": {"headphones": 30, "earbuds": 12}
}
}To filter by facet, send facet_filters in the search request:
{
"query": "wireless headphones",
"search_context": { "..." : "..." },
"facet_filters": {
"color": ["black"],
"brand": ["sony", "bose"]
}
}Configuration
Collection Settings
Each integration is configured as a "collection" with its own settings managed by XTAL. These control search behavior, display, and features:
| Field | Type | Required | Description |
|---|---|---|---|
| results_per_page | number | No | Default number of results per search (default: 48) |
| query_enhancement_enabled | boolean | No | AI query expansion for better recall (default: true) |
| aspects_enabled | boolean | No | AI-generated aspect suggestions (default: true) |
| store_type | string | No | Store category for AI context (e.g., "home goods retailer") |
| snippet_search_selector | string | No | CSS selector for the search input (default: input[type="search"]) |
| snippet_display_mode | "overlay" | "fullpage" | No | How the JS snippet renders results |
UTM Tracking
All product links generated by XTAL include UTM parameters for attribution tracking. These are appended automatically:
Features
The following features are available per collection:
AI Aspects
Generates natural-language refinement options for each query (e.g., "noise cancelling", "under $50"). Displayed as clickable chips that filter results.
Explain
On-demand AI explanation for why a specific product was returned for a query. Helps build user trust in search relevance.
Query Enhancement
Automatically expands queries using AI to improve recall. For example, "comfy chair" may be enhanced to include "ergonomic", "cushioned", "lounge".
Next Steps
To begin your integration, we recommend:
- Choose an integration approach — JS snippet for quick deployment, or server-side API for full control.
- Share your platform constraints — Can you add custom script tags to the storefront? Do you have server-side extension points for API calls?
- Schedule a technical walkthrough — We'll walk through the API together and answer any questions about data formats, authentication, or customization.
Contact: team@xtalsearch.com
XTAL Search · xtalsearch.com