prefixbox_api.md 16.7 KB
Edit Raw Blame History


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 示例：
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)


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


响应格式：
{
  "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
否
客户数据平台偏好数据


请求示例：
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


完整带过滤器的请求：
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


响应格式：
{
  "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}

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

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


响应格式：
{
  "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

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

请求参数：
{
  "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

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

请求参数：
{
  "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

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


响应格式：
{
  "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
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 - 完成购买


请求示例：
{
  "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

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

请求格式：
{
  "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 错误响应格式
{
  "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 集成
// 初始化 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 示例
# 自动完成
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 集成示例
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 性能优化

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

14.2 提升搜索相关性

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

14.3 用户体验

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


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。