# Prefixbox Search API 完整文档

*基于公开信息整理的 Prefixbox Search API 技术文档*

*官方接口文档*
https://api-docs.prefixbox.com/#search-api


---

## 概述

Prefixbox Search API 是一个基于 AI 的电商搜索解决方案，提供全文搜索、向量搜索和混合搜索功能。该 API 支持自动完成、搜索建议、商品过滤、排序等核心电商搜索功能。

**核心特性：**
- 混合搜索（文本 + 向量 + GPT 技术）
- 自然语言查询理解
- 动态重排序
- 同义词管理
- 多语言支持

---

## 1. 基础信息

### 1.1 API 端点

```
基础 URL: https://api.prefixbox.com
版本: v1/v2 (根据集成方式不同)
```

### 1.2 认证方式

**API Key 认证**
- 在 Prefixbox API Portal 的 Profile 页面获取 Search API Key
- 所有请求必须在 Header 中包含：`Authorization: Bearer YOUR_SEARCH_API_KEY`
- 同时需要提供 Search Engine Identifier

**Header 示例：**
```http
Authorization: Bearer pb_live_abc123xyz...
X-Search-Engine-Id: your-engine-identifier
```

---

## 2. 核心 API 端点

### 2.1 自动完成 API (Autocomplete API)

**端点：** `GET /autocomplete`

**功能：** 当用户在搜索框输入时提供实时查询建议、分类建议和商品建议。

**请求参数：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `q` | string | 是 | 用户输入的查询字符串 |
| `limit` | integer | 否 | 返回建议的最大数量 (默认: 10) |
| `type` | string | 否 | 建议类型: `all`, `queries`, `categories`, `products` (默认: all) |
| `lang` | string | 否 | ISO 639-1 语言代码 (如: en, de, fr) |

**请求示例：**
```http
GET https://api.prefixbox.com/autocomplete?q=apple&limit=8&lang=en
Authorization: Bearer pb_live_abc123xyz...
X-Search-Engine-Id: your-engine-identifier
```

**响应格式：**
```json
{
  "query": "apple",
  "suggestions": {
    "queries": [
      {"text": "apple iphone", "count": 1250},
      {"text": "apple watch", "count": 890},
      {"text": "apple airpods", "count": 650}
    ],
    "categories": [
      {"id": "cat_001", "name": "Smartphones", "path": "Electronics/Mobile"},
      {"id": "cat_002", "name": "Accessories", "path": "Electronics/Accessories"}
    ],
    "products": [
      {
        "id": "prod_12345",
        "name": "Apple iPhone 15 Pro",
        "image": "https://cdn.example.com/iphone15.jpg",
        "price": 999.99,
        "currency": "USD",
        "url": "https://store.example.com/products/iphone-15-pro"
      }
    ]
  },
  "latency_ms": 45
}
```

---

### 2.2 搜索 API (Search API)

**端点：** `GET /search`

**功能：** 执行完整搜索并返回商品结果、过滤器、排序选项等。

**请求参数：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `q` | string | 是 | 搜索查询字符串 |
| `page` | integer | 否 | 页码 (默认: 1) |
| `page_size` | integer | 否 | 每页商品数量 (默认: 24, 最大: 100) |
| `sort` | string | 否 | 排序方式: `relevance`, `price_asc`, `price_desc`, `newest`, `popularity` |
| `filters` | object | 否 | 过滤器对象 `{"brand": ["Apple", "Samsung"], "price_range": {"min": 500, "max": 1000}}` |
| `lang` | string | 否 | 语言代码 |
| `user_id` | string | 否 | 用户ID（用于个性化）|
| `cdp_data` | object | 否 | 客户数据平台偏好数据 |

**请求示例：**
```http
GET https://api.prefixbox.com/search?q=running+shoes&page=1&page_size=24&sort=relevance
Authorization: Bearer pb_live_abc123xyz...
X-Search-Engine-Id: your-engine-identifier
```

**完整带过滤器的请求：**
```http
GET https://api.prefixbox.com/search?q=running+shoes&filters={"brand":["Nike","Adidas"],"price_range":{"min":50,"max":200},"size":["8","9","10"]}
Authorization: Bearer pb_live_abc123xyz...
X-Search-Engine-Id: your-engine-identifier
```

**响应格式：**
```json
{
  "search_id": "search_abc123xyz789",
  "query": "running shoes",
  "total_results": 1456,
  "page": 1,
  "page_size": 24,
  "total_pages": 61,
  "latency_ms": 120,
  "products": [
    {
      "id": "prod_67890",
      "name": "Nike Air Zoom Pegasus",
      "description": "Responsive running shoes with Zoom Air cushioning",
      "image": "https://cdn.example.com/nike-pegasus.jpg",
      "price": 129.99,
      "original_price": 159.99,
      "currency": "USD",
      "url": "https://store.example.com/products/nike-air-zoom-pegasus",
      "availability": "in_stock",
      "brand": "Nike",
      "category": "Running Shoes",
      "score": 0.987
    }
  ],
  "filters": [
    {
      "name": "brand",
      "type": "multiselect",
      "values": [
        {"value": "Nike", "count": 456},
        {"value": "Adidas", "count": 389},
        {"value": "Asics", "count": 234}
      ]
    },
    {
      "name": "price",
      "type": "range",
      "min": 29.99,
      "max": 299.99
    },
    {
      "name": "size",
      "type": "multiselect",
      "values": [
        {"value": "7", "count": 156},
        {"value": "8", "count": 234},
        {"value": "9", "count": 289}
      ]
    }
  ],
  "sort_options": [
    {"value": "relevance", "label": "Relevance"},
    {"value": "price_asc", "label": "Price: Low to High"},
    {"value": "price_desc", "label": "Price: High to Low"},
    {"value": "newest", "label": "Newest First"},
    {"value": "popularity", "label": "Most Popular"}
  ],
  "related_keywords": ["trail running", "marathon shoes", "lightweight trainers"],
  "related_categories": [
    {"id": "cat_sports", "name": "Sports & Outdoors"},
    {"id": "cat_footwear", "name": "Footwear"}
  ],
  "personalized": false,
  "ai_reranking": true
}
```

---

### 2.3 商品详情 API (Product Details API)

**端点：** `GET /products/{product_id}`

**功能：** 获取单个商品的详细信息。

**请求示例：**
```http
GET https://api.prefixbox.com/products/prod_67890
Authorization: Bearer pb_live_abc123xyz...
X-Search-Engine-Id: your-engine-identifier
```

**响应格式：**
```json
{
  "id": "prod_67890",
  "name": "Nike Air Zoom Pegasus",
  "description": "Responsive running shoes with Zoom Air cushioning",
  "long_description": "Detailed product description...",
  "images": [
    "https://cdn.example.com/nike-pegasus-1.jpg",
    "https://cdn.example.com/nike-pegasus-2.jpg"
  ],
  "price": 129.99,
  "original_price": 159.99,
  "currency": "USD",
  "url": "https://store.example.com/products/nike-air-zoom-pegasus",
  "availability": "in_stock",
  "stock_quantity": 45,
  "brand": "Nike",
  "category": "Running Shoes",
  "attributes": {
    "color": ["Black", "White", "Blue"],
    "size": ["7", "8", "9", "10", "11", "12"],
    "material": "Mesh and Rubber",
    "weight": "280g"
  },
  "reviews": {
    "average_rating": 4.5,
    "count": 234
  },
  "tags": ["marathon", "neutral", "cushioned"]
}
```

---

### 2.4 分类页面 API (Collection API)

**端点：** `GET /collections/{collection_id}`

**功能：** 获取分类页面的商品列表。

**请求参数：**

| 参数 | 类型 | 说明 |
|------|------|------|
| `collection_id` | string | 分类ID |
| `page` | integer | 页码 |
| `page_size` | integer | 每页数量 |
| `sort` | string | 排序方式 |
| `filters` | object | 过滤器 |

**响应格式：** 与 Search API 类似，但返回的是特定分类的商品

---

## 3. 高级功能 API

### 3.1 个性化搜索 API

**端点：** `GET /search/personalized`

**功能：** 基于用户偏好数据返回个性化排序结果。

**请求参数：**
```json
{
  "q": "running shoes",
  "user_id": "user_12345",
  "cdp_data": {
    "preferred_brands": ["Nike", "Adidas"],
    "preferred_size": "9",
    "preferred_color": "Black",
    "past_purchases": ["prod_111", "prod_222"]
  }
}
```

---

### 3.2 AI 重排序 API

**端点：** `POST /search/rerank`

**功能：** 基于用户行为数据动态重排搜索结果。

**请求参数：**
```json
{
  "search_id": "search_abc123xyz789",
  "user_interactions": {
    "clicks": ["prod_67890", "prod_67891"],
    "hover_time_ms": 2500,
    "previous_searches": ["trail running"]
  }
}
```

---

## 4. 推荐 API (AI Recommend)

### 4.1 相关产品推荐

**端点：** `GET /recommendations/related`

**请求参数：**
```http
GET /recommendations/related?product_id=prod_67890&limit=6
```

**响应格式：**
```json
{
  "product_id": "prod_67890",
  "recommendations": [
    {
      "id": "prod_67891",
      "name": "Nike Dri-FIT Running Socks",
      "reason": "Frequently bought together"
    },
    {
      "id": "prod_67892",
      "name": "Nike Running Cap",
      "reason": "Similar category"
    }
  ]
}
```

---

### 4.2 热门商品推荐

**端点：** `GET /recommendations/trending`

```http
GET /recommendations/trending?category=running&limit=8
```

---

## 5. 分析追踪 API

### 5.1 搜索事件追踪

**端点：** `POST /analytics/search-event`

**功能：** 追踪用户搜索行为以优化搜索相关性。

**事件类型：**
- `search_impression` - 搜索结果展示
- `search_click` - 用户点击结果
- `search_add_to_cart` - 添加商品到购物车
- `search_purchase` - 完成购买

**请求示例：**
```json
{
  "search_id": "search_abc123xyz789",
  "event_type": "search_click",
  "user_id": "user_12345",
  "product_id": "prod_67890",
  "position": 1,
  "timestamp": "2025-01-15T10:30:00Z"
}
```

---

## 6. 实时目录更新 API

**端点：** `POST /catalog/update`

**功能：** 实时更新商品目录数据。

**请求格式：**
```json
{
  "updates": [
    {
      "product_id": "prod_67890",
      "field": "stock_quantity",
      "value": 23,
      "action": "update"
    },
    {
      "product_id": "prod_67891",
      "action": "delete"
    }
  ]
}
```

---

## 7. 错误处理

### 7.1 HTTP 状态码

| 状态码 | 说明 |
|--------|------|
| `200` | 请求成功 |
| `400` | 请求参数错误 |
| `401` | 认证失败 - API Key 无效或缺失 |
| `403` | 权限不足 |
| `404` | 资源未找到 |
| `429` | 请求频率限制 |
| `500` | 服务器内部错误 |

### 7.2 错误响应格式

```json
{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is invalid or expired.",
    "status": 401,
    "request_id": "req_123456789"
  }
}
```

---

## 8. 代码集成示例

### 8.1 JavaScript/Frontend 集成

```javascript
// 初始化 Prefixbox 客户端
const prefixbox = new PrefixboxClient({
  apiKey: 'pb_live_abc123xyz...',
  searchEngineId: 'your-engine-identifier',
  language: 'en'
});

// 自动完成
const suggestions = await prefixbox.autocomplete({
  query: 'run',
  limit: 8
});

// 搜索
const searchResults = await prefixbox.search({
  query: 'running shoes',
  page: 1,
  pageSize: 24,
  filters: {
    brand: ['Nike', 'Adidas'],
    priceRange: { min: 50, max: 200 }
  }
});

// 追踪事件
prefixbox.trackEvent('search_click', {
  searchId: searchResults.searchId,
  productId: 'prod_67890',
  position: 1
});
```

### 8.2 cURL 示例

```bash
# 自动完成
curl -X GET "https://api.prefixbox.com/autocomplete?q=apple&limit=5" \
     -H "Authorization: Bearer pb_live_abc123xyz..." \
     -H "X-Search-Engine-Id: your-engine-identifier"

# 搜索
curl -X GET "https://api.prefixbox.com/search?q=laptop&page=1&page_size=24" \
     -H "Authorization: Bearer pb_live_abc123xyz..." \
     -H "X-Search-Engine-Id: your-engine-identifier"
```

### 8.3 Python 集成示例

```python
import requests

class PrefixboxClient:
    def __init__(self, api_key, search_engine_id):
        self.base_url = "https://api.prefixbox.com"
        self.headers = {
            "Authorization": f"Bearer {api_key}",
            "X-Search-Engine-Id": search_engine_id,
            "Content-Type": "application/json"
        }
    
    def autocomplete(self, query, limit=10):
        endpoint = f"{self.base_url}/autocomplete"
        params = {"q": query, "limit": limit}
        response = requests.get(endpoint, headers=self.headers, params=params)
        return response.json()
    
    def search(self, query, page=1, page_size=24, filters=None):
        endpoint = f"{self.base_url}/search"
        params = {
            "q": query,
            "page": page,
            "page_size": page_size
        }
        if filters:
            params["filters"] = filters
        
        response = requests.get(endpoint, headers=self.headers, params=params)
        return response.json()

# 使用示例
client = PrefixboxClient(
    api_key="pb_live_abc123xyz...",
    search_engine_id="your-engine-identifier"
)

# 执行搜索
results = client.search(
    query="wireless headphones",
    filters={"brand": ["Sony", "Bose"], "price_range": {"min": 100, "max": 300}}
)

print(f"找到 {results['total_results']} 个商品")
for product in results['products']:
    print(f"- {product['name']}: ${product['price']}")
```

---

## 9. SDK 和库

Prefixbox 提供以下官方 SDK：

- **JavaScript SDK**: `npm install @prefixbox/search-js`
- **React SDK**: `npm install @prefixbox/react-search`
- **Python SDK**: `pip install prefixbox-search`
- **PHP SDK**: `composer require prefixbox/search`

---

## 10. 集成方式

### 10.1 API 集成

**适用场景：** 需要完全自定义 UI 和用户体验

**客户职责：**
- 提供商品 Feed URL
- 实现与 Prefixbox API 的通信
- 实现搜索 UX 界面
- 实现用户行为追踪
- Bug 修复和发布

**Prefixbox 职责：**
- 在 Admin Portal 配置搜索模块
- 定制功能需求
- 测试和报告 Bug
- 运行 A/B 测试

### 10.2 前端 JavaScript 集成

**适用场景：** 快速部署，最小化开发工作量

**客户职责：**
- 提供带 header/footer 的空搜索结果页
- 提供商品 Feed URL
- 在网站中插入 Prefixbox JavaScript

**Prefixbox 职责：**
- 配置搜索模块
- 定制外观和功能
- 测试、预览和修复 Bug
- 发布到生产环境

---

## 11. 商品 Feed 格式

Prefixbox 要求提供兼容的商品 Feed：

**必需字段：**
- `id` - 商品唯一标识符
- `name` - 商品名称
- `url` - 商品页面 URL
- `price` - 价格
- `currency` - 货币代码
- `availability` - 库存状态

**推荐字段：**
- `description` - 商品描述
- `image` - 商品图片 URL
- `brand` - 品牌
- `category` - 分类
- `attributes` - 商品属性（颜色、尺寸等）
- `created_at` - 创建日期
- `popularity_score` - 热门度分数

**支持格式：** JSON, XML, CSV

---

## 12. 限制和配额

### 12.1 API 请求限制

| 套餐 | 月请求配额 | 每分钟限制 |
|------|-----------|-----------|
| Starter | 20,000 | 100 |
| Growth | 200,000 | 500 |
| Grow+ | 600,000-900,000 | 1,000 |
| Enterprise | 自定义 | 自定义 |

### 12.2 什么算作 API 请求？

- **自动完成：** 每个字符输入 = 1 次请求
- **搜索：** 每次搜索 = 1 次请求
- **过滤/排序：** 每次操作 = 1 次请求
- **分页：** 每次翻页 = 1 次请求

**示例：** 用户输入 "apple"（6 次自动完成请求）+ 执行搜索（1 次）+ 过滤（1 次）+ 翻页（1 次）= **共 9 次 API 请求**

---

## 13. 支持和资源

### 13.1 官方资源

- **API 文档门户：** https://api-docs.prefixbox.com
- **开发者中心：** https://developers.prefixbox.com
- **技术文档：** https://www.prefixbox.com/en-us/technical
- **集成指南：** https://www.prefixbox.com/en-us/technical/integration

### 13.2 支持级别

| 支持级别 | 可用套餐 | 响应时间 |
|---------|---------|---------|
| 标准支持 | Starter, Growth | 24-48 小时 |
| 高级支持 | Grow+ | 4 小时 |
| 专属支持 | Enterprise | 1 小时 |

---

## 14. 最佳实践

### 14.1 性能优化

1. **缓存自动完成结果** - 减少重复请求
2. **延迟搜索** - 用户停止输入 300ms 后再发送请求
3. **分页加载** - 使用无限滚动或分页
4. **图片优化** - 使用 CDN 和适当尺寸的图片

### 14.2 提升搜索相关性

1. **配置同义词** - 连接不同词汇（如 "sneakers" = "trainers"）
2. **设置字段权重** - 提升重要字段的权重（如 name > description）
3. **使用 A/B 测试** - 测试不同配置对转化率的影响
4. **分析零结果搜索** - 识别缺失商品或查询问题

### 14.3 用户体验

1. **显示搜索建议** - 帮助用户快速找到相关查询
2. **保留搜索上下文** - 支持返回搜索结果
3. **移动端优化** - 确保触摸友好的界面
4. **加载状态** - 提供清晰的加载指示

---

## 15. 常见问题

### Q: API 返回 429 错误怎么办？
A: 表示达到速率限制。实现指数退避重试策略，或升级到更高配额的套餐。

### Q: 如何处理多语言搜索？
A: 在请求中使用 `lang` 参数，并确保商品 Feed 包含翻译内容。

### Q: 可以自定义搜索算法吗？
A: 可以在 Prefixbox Admin Portal 中调整字段权重和同义词规则。

### Q: 支持语音搜索吗？
A: 是的，Prefixbox AI Agent 支持自然语言查询和语音搜索集成。

### Q: 如何集成到移动应用？
A: 通过 API 集成方式，使用 iOS/Android 原生开发或 React Native 调用 REST API。