Local Descriptions (Search API)
Paid Local Descriptions proxy via x402 pay-per-use (HTTP 402).
Prerequisites: This skill requires x402-payment. Complete the setup steps before first use.
Two-step flow: This endpoint requires POI IDs from a prior web search.
- 1. Call
web-search with result_filter=locations to get POI IDs from INLINECODE2 - Pass those IDs to this endpoint to get AI-generated descriptions
Service URLs
| Role | Domain |
|---|
| API Provider | https://www.cpbox.io |
| Facilitator |
https://www.cppay.finance |
Endpoint (Agent Interface)
CODEBLOCK0
Payment Flow (x402 Protocol)
- 1. First request ->
402 Payment Required with requirements JSON - Sign & retry with
PAYMENT-SIGNATURE -> result JSON
With @springmint/x402-payment or x402-sdk-go, payment is automatic.
Quick Start (cURL)
Get POI Description
CODEBLOCK1
Multiple POIs
CODEBLOCK2
Note: POI IDs are opaque strings returned in web search locations.results[].id. They are valid for approximately 8 hours. The example IDs above are for illustration — fetch fresh IDs via web-search with result_filter=locations.
Using with x402-payment
CODEBLOCK3
Parameters
| Parameter | Type | Required | Default | Description |
|---|
| INLINECODE10 | string[] | Yes | — | POI IDs from web search locations.results[].id (1-20, repeated: ?ids=a&ids=b) |
Response Format
Response Fields
| Field | Type | Description |
|---|
| INLINECODE13 | string | Always INLINECODE14 |
| INLINECODE15 |
array | List of description objects (entries may be
null) |
|
results[].type | string | Always
"local_description" |
|
results[].id | string | POI identifier matching the request |
|
results[].description | string? | AI-generated markdown description, or
null if unavailable |
Example Response
CODEBLOCK4
Getting POI IDs
POI IDs come from the Web Search API (web-search) with result_filter=locations:
CODEBLOCK5
Use Cases
- - Local business overview: Pair with
local-pois to get both structured data (hours, ratings) and narrative descriptions - Travel/tourism enrichment: Add descriptive context to POIs for travel planning or destination guides
- Search results augmentation: Supplement web search results with AI-generated summaries of local businesses
Notes
- - Always markdown: Descriptions use
### headings, bullet lists, bold/italics — always formatted as markdown - Travel-guide tone: Typically 200-400 words covering what makes the POI notable
- AI-generated: Descriptions are AI-generated based on web search context, not sourced from business profiles
- Availability: Not all POIs have descriptions —
description may be INLINECODE27 - Max IDs: Up to 20 IDs per request
本地描述（搜索API）
通过 x402按次付费（HTTP 402）提供的付费本地描述代理。
前置条件：此技能需要x402支付。首次使用前请完成设置步骤。
两步流程：此端点需要先前网络搜索中的POI ID。
- 1. 使用 result_filter=locations 调用 web-search，从 locations.results[].id 获取POI ID
- 将这些ID传递给此端点以获取AI生成的描述
服务URL
| 角色 | 域名 |
|---|
| API提供方 | https://www.cpbox.io |
| 协调方 |
https://www.cppay.finance |
端点（代理接口）
http
GET /api/x402/local-descriptions
支付流程（x402协议）
- 1. 首次请求 -> 返回包含需求JSON的 402 Payment Required
- 签名并重试，携带 PAYMENT-SIGNATURE -> 返回结果JSON
使用 @springmint/x402-payment 或 x402-sdk-go 时，支付是自动的。
快速开始（cURL）
获取POI描述
bash
curl -s https://www.cpbox.io/api/x402/local-descriptions?ids=loc4CQWMJWLD4VBEBZ62XQLJTGK6YCJEEJDNAAAAAAA%3D \
-H Accept: application/json \
-H Accept-Encoding: gzip
多个POI
bash
curl -s https://www.cpbox.io/api/x402/local-descriptions \
-H Accept: application/json \
-H Accept-Encoding: gzip \
-G \
--data-urlencode ids=loc4CQWMJWLD4VBEBZ62XQLJTGK6YCJEEJDNAAAAAAA= \
--data-urlencode ids=loc4HTAVTJKP4RBEBZCEMBI3NG26YD4II4PATIHPDYI=
注意：POI ID是在网络搜索中返回的不透明字符串，位于 locations.results[].id。它们大约有效8小时。上述示例ID仅供说明——请通过 result_filter=locations 的 web-search 获取最新的ID。
与x402-payment配合使用
bash
npx @springmint/x402-payment \
--url https://www.cpbox.io/api/x402/local-descriptions?ids=loc4CQWMJWLD4VBEBZ62XQLJTGK6YCJEEJDNAAAAAAA%3D \
--method GET
参数
| 参数 | 类型 | 必填 | 默认值 | 描述 |
|---|
| ids | string[] | 是 | — | 来自网络搜索 locations.results[].id 的POI ID（1-20个，重复使用：?ids=a&ids=b） |
响应格式
响应字段
| 字段 | 类型 | 描述 |
|---|
| type | string | 始终为 local_descriptions |
| results |
array | 描述对象列表（条目可能为 null） |
| results[].type | string | 始终为 local_description |
| results[].id | string | 与请求匹配的POI标识符 |
| results[].description | string? | AI生成的Markdown格式描述，若不可用则为 null |
示例响应
json
{
type: local_descriptions,
results: [
{
type: local_description,
id: loc4CQWMJWLD4VBEBZ62XQLJTGK6YCJEEJDNAAAAAAA=,
description: ### 概述\n一家以手工咖啡闻名的舒适社区咖啡馆...
}
]
}
获取POI ID
POI ID来自网络搜索API（web-search），需设置 result_filter=locations：
bash
1. 搜索本地商家
curl -s https://www.cpbox.io/api/x402/web-search?q=restaurants+san+francisco&result_filter=locations \
-H Accept: application/json
2. 从 locations.results[].id 提取POI ID
3. 将这些ID用于 local/pois 和 local/descriptions
使用场景
- - 本地商家概览：与 local-pois 配合使用，同时获取结构化数据（营业时间、评分）和叙述性描述
- 旅行/旅游内容增强：为旅行规划或目的地指南中的POI添加上下文描述
- 搜索结果增强：用AI生成的本地商家摘要补充网络搜索结果
注意事项
- - 始终为Markdown格式：描述使用 ### 标题、项目符号列表、粗体/斜体——始终格式化为Markdown
- 旅行指南语气：通常200-400字，涵盖POI的亮点
- AI生成：描述基于网络搜索上下文由AI生成，并非来自商家资料
- 可用性：并非所有POI都有描述——description 可能为 null
- 最大ID数量：每次请求最多20个ID
