local-descriptions

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Local Descriptions (Search API)

本地描述（Search API）

Requires API Key: Get one at https://api.search.brave.com

Plan: Included in the Search plan. See https://api-dashboard.search.brave.com/app/subscriptions/subscribe

Two-step flow: This endpoint requires POI IDs from a prior web search.
Call
web-search
with
result_filter=locations
to get POI IDs from
locations.results[].id
Pass those IDs to this endpoint to get AI-generated descriptions

需API Key：前往https://api.search.brave.com 获取

套餐要求：包含在搜索套餐中，详情查看https://api-dashboard.search.brave.com/app/subscriptions/subscribe

两步流程：该接口需要从前置的网络搜索请求中获取POI ID
调用
web-search
并设置
result_filter=locations
，从
locations.results[].id
字段获取POI ID
将这些ID传入本接口即可获取AI生成的描述

Quick Start (cURL)

快速开始（cURL）

Get POI Description

获取POI描述

bash

curl -s "https://api.search.brave.com/res/v1/local/descriptions?ids=loc4CQWMJWLD4VBEBZ62XQLJTGK6YCJEEJDNAAAAAAA%3D" \
  -H "Accept: application/json" \
  -H "Accept-Encoding: gzip" \
  -H "X-Subscription-Token: ${BRAVE_SEARCH_API_KEY}"

bash

curl -s "https://api.search.brave.com/res/v1/local/descriptions?ids=loc4CQWMJWLD4VBEBZ62XQLJTGK6YCJEEJDNAAAAAAA%3D" \
  -H "Accept: application/json" \
  -H "Accept-Encoding: gzip" \
  -H "X-Subscription-Token: ${BRAVE_SEARCH_API_KEY}"

Multiple POIs

多个POI

bash

curl -s "https://api.search.brave.com/res/v1/local/descriptions" \
  -H "Accept: application/json" \
  -H "Accept-Encoding: gzip" \
  -H "X-Subscription-Token: ${BRAVE_SEARCH_API_KEY}" \
  -G \
  --data-urlencode "ids=loc4CQWMJWLD4VBEBZ62XQLJTGK6YCJEEJDNAAAAAAA=" \
  --data-urlencode "ids=loc4HTAVTJKP4RBEBZCEMBI3NG26YD4II4PATIHPDYI="

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

bash

curl -s "https://api.search.brave.com/res/v1/local/descriptions" \
  -H "Accept: application/json" \
  -H "Accept-Encoding: gzip" \
  -H "X-Subscription-Token: ${BRAVE_SEARCH_API_KEY}" \
  -G \
  --data-urlencode "ids=loc4CQWMJWLD4VBEBZ62XQLJTGK6YCJEEJDNAAAAAAA=" \
  --data-urlencode "ids=loc4HTAVTJKP4RBEBZCEMBI3NG26YD4II4PATIHPDYI="

注意：POI ID是网络搜索接口返回的不透明字符串，有效期约为8小时。上述示例ID仅用于演示，请通过设置了

result_filter=locations

的

web-search

请求获取最新的ID。

Endpoint

接口地址

http

GET https://api.search.brave.com/res/v1/local/descriptions

Authentication:

X-Subscription-Token: <API_KEY>

header

http

GET https://api.search.brave.com/res/v1/local/descriptions

鉴权方式：通过

X-Subscription-Token: <API_KEY>

请求头鉴权

Parameters

参数

Parameter	Type	Required	Default	Description
`ids`	string[]	Yes	—	POI IDs from web search `locations.results[].id` (1-20, repeated: `?ids=a&ids=b` )

参数	类型	必填	默认值	描述
`ids`	string[]	是	—	从网络搜索 `locations.results[].id` 字段获取的POI ID，支持1-20个，传参格式： `?ids=a&ids=b`

Response Format

响应格式

Response Fields

响应字段

Field	Type	Description
`type`	string	Always `"local_descriptions"`
`results`	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

字段	类型	描述
`type`	string	固定为 `"local_descriptions"`
`results`	array	描述对象列表，条目可能为 `null`
`results[].type`	string	固定为 `"local_description"`
`results[].id`	string	与请求对应的POI标识符
`results[].description`	string?	AI生成的markdown格式描述，无可用内容时返回 `null`

Example Response

示例响应

json

{
  "type": "local_descriptions",
  "results": [
    {
      "type": "local_description",
      "id": "loc4CQWMJWLD4VBEBZ62XQLJTGK6YCJEEJDNAAAAAAA=",
      "description": "### Overview\nA cozy neighborhood cafe known for its **artisanal coffee**..."
    }
  ]
}

json

{
  "type": "local_descriptions",
  "results": [
    {
      "type": "local_description",
      "id": "loc4CQWMJWLD4VBEBZ62XQLJTGK6YCJEEJDNAAAAAAA=",
      "description": "### Overview\nA cozy neighborhood cafe known for its **artisanal coffee**..."
    }
  ]
}

Getting POI IDs

获取POI ID

POI IDs come from the Web Search API (

web-search

) with

result_filter=locations

bash

undefined

POI ID来自设置了

result_filter=locations

的Web Search API（

web-search

）：

bash

undefined

1. Search for local businesses

1. 搜索本地商家

curl -s "https://api.search.brave.com/res/v1/web/search?q=restaurants+san+francisco&result_filter=locations"
-H "Accept: application/json"
-H "X-Subscription-Token: ${BRAVE_SEARCH_API_KEY}"

2. Extract POI IDs from locations.results[].id

2. 从locations.results[].id提取POI ID

3. Use those IDs with local/pois and local/descriptions

3. 将这些ID用于local/pois和local/descriptions接口

undefined

undefined

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

本地商家概览：与
```
local-pois
```
接口搭配使用，可同时获取结构化数据（营业时间、评分）和叙述性描述
旅行/旅游内容丰富：为POI添加描述性上下文，用于旅行规划或目的地指南
搜索结果增强：用AI生成的本地商家摘要补充网页搜索结果

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
```
null
```
Max IDs: Up to 20 IDs per request

始终为markdown格式：描述使用
```
###
```
标题、无序列表、*粗体/斜体格式，统一为markdown排版
旅行指南风格：通常为200-400字，内容涵盖POI的特色亮点
AI生成：描述基于网页搜索上下文AI生成，并非来自商家官方资料
可用性：并非所有POI都有对应描述，
```
description
```
可能为
```
null
```
ID数量上限：每次请求最多传入20个ID