local-place-search

地点搜索（Search API）

需要 API 密钥：请前往 https://api.search.brave.com 获取

套餐：包含在 Search 套餐中（需使用 locations 选项）。请参阅 https://api-dashboard.search.brave.com/app/subscriptions/subscribe

独立使用：与 local-pois 和 local-descriptions 不同，此端点不需要通过先前的网页搜索获取 POI ID。直接提供地点和可选的查询即可。

快速开始（cURL）

按查询词和坐标搜索

curl -s "https://api.search.brave.com/res/v1/local/place_search" \
  -H "Accept: application/json" \
  -H "Accept-Encoding: gzip" \
  -H "X-Subscription-Token: ${BRAVE_SEARCH_API_KEY}" \
  -G \
  --data-urlencode "q=coffee shops" \
  --data-urlencode "latitude=37.7749" \
  --data-urlencode "longitude=-122.4194" \
  --data-urlencode "radius=5000"

按查询词和地点字符串搜索

curl -s "https://api.search.brave.com/res/v1/local/place_search" \
  -H "Accept: application/json" \
  -H "Accept-Encoding: gzip" \
  -H "X-Subscription-Token: ${BRAVE_SEARCH_API_KEY}" \
  -G \
  --data-urlencode "q=sushi restaurants" \
  --data-urlencode "location=tokyo japan" \
  --data-urlencode "country=JP" \
  --data-urlencode "search_lang=en"

浏览常规 POI（无查询词）

curl -s "https://api.search.brave.com/res/v1/local/place_search" \
  -H "Accept: application/json" \
  -H "Accept-Encoding: gzip" \
  -H "X-Subscription-Token: ${BRAVE_SEARCH_API_KEY}" \
  -G \
  --data-urlencode "latitude=48.8566" \
  --data-urlencode "longitude=2.3522" \
  --data-urlencode "radius=3000" \
  --data-urlencode "country=FR"

端点

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

身份验证：X-Subscription-Token: <API_KEY> 请求头

参数

地点（可选，但建议提供）

提供地理位置锚点可提高精确度。你可以使用坐标（latitude + longitude）或 location 字符串。如果提供了 q，则允许两者都省略——结果将从全球范围内获取，精确度可能较低。若三者（q、latitude/longitude 和 location）全部省略，则返回 HTTP 422。

参数	类型	必需	默认值	说明
latitude	float	有条件必需	—	纬度（-90.0 至 90.0）。必须与 longitude 一同提供
longitude	float	有条件必需	—	经度（-180.0 至 180.0）。必须与 latitude 一同提供
location	string	否	—	地点字符串，可替代坐标。美国：<city> <state> <country>（例如，san francisco ca united states）。美国以外：<city> <country>（例如，tokyo japan）。不区分大小写，无需逗号。使用英语或当地最常用的语言效果最佳

搜索

参数	类型	必需	默认值	说明
q	string	否	—	自由文本查询（例如，coffee shops、pizza）。完全可选——省略时，将返回指定区域内的常规 POI

其他选项

参数	类型	必需	默认值	说明
radius	float	否	—	围绕所提供坐标的搜索半径偏好值，单位为米。不是硬性范围限制——结果可能超出此范围。无上限
count	int	否	20	所有类别中返回的条目总数（1–100），而不仅是 results——地址查询可能会将全部数量用在 addresses/streets 上
geoloc	string	否	—	用户地理位置，格式为 <latitude>x<longitude>（例如，40.7128x-74.0060），用于计算 distance
country	string	否	US	搜索国家（2 个字母的国家/地区代码或 ALL）
search_lang	string	否	en	搜索结果的语言（至少 2 个字符的语言代码）
ui_lang	string	否	en-US	界面语言（区域设置代码，例如，en-US）
units	string	否	metric	计量单位：metric 或 imperial
safesearch	string	否	strict	安全搜索级别：off、moderate 或 strict
spellcheck	bool	否	true	是否对查询应用拼写检查

响应格式

顶层字段

字段	类型	描述
type	string	始终为 "locations"
results	array	LocationResult 对象列表（单个 POI）
cities	array	匹配的城市，type: "city" — 参见地理地点字段
countries	array	匹配的国家，type: "country"
regions	array	匹配的地区，type: "region"
neighborhoods	array	匹配的街区，type: "neighborhood"
addresses	array	AddressResult 对象列表，type: "address" — 具体的街道和门牌号位置
streets	array	AddressResult 对象列表，type: "street" — 整条街道
mixed	array	ResultReference 排序提示，用于描述如何在 SERP 上交错显示各个分类
location	object?	已解析的位置信息
location.coordinates	[float, float]	已解析中心点的 [latitude, longitude]
location.name	string	已解析的位置名称（例如，"Helsinki"）
location.country	string	两字母国家代码（例如，"FI"）

缺失的分类视为空。对于典型的 POI 类查询，通常只有 results 有内容，因此不呈现丰富 SERP 的客户端可以忽略其他字段——但地址或街道类查询除外；这类查询可能返回空的 results，并将所有匹配项放在 addresses/streets 中。

LocationResult 字段

results 中的每个项目都是一个 LocationResult：

字段	类型	描述
type	string	始终为 "location_result"
title	string	商家/POI 名称
url	string	规范 URL
description	string?	简短描述或类别标签（例如，"Coffee Shop"）
provider_url	string	提供方页面 URL
id	string?	不透明的 POI 标识符（有效期约 8 小时，可与 local-pois 和 local-descriptions 配合使用）
coordinates	[float, float]?	[latitude, longitude]
postal_address	object	displayAddress，以及可选的 streetAddress、addressLocality、addressRegion、postalCode、country
contact.telephone	string?	电话号码
contact.email	string?	电子邮箱地址
rating.ratingValue	float?	平均评分
rating.bestRating	float?	最高可能评分
rating.reviewCount	int?	评价数量
rating.is_tripadvisor	bool	评分是否来自 Tripadvisor
opening_hours.current_day	object[]?	今日营业时间（abbr_name、full_name、opens、closes）
opening_hours.days	object[][]?	一周中每天的营业时间
categories	string[]	商家类别（默认值为 []）
price_range	string?	价格标示，例如 $、$$、$$ - $$$
serves_cuisine	string[]?	菜系类型（餐厅）
distance.value	float?	与搜索位置的距离
distance.units	string?	距离单位
icon_category	string?	图标类别标识（例如，cafe）
thumbnail.src	string?	缩略图 URL
thumbnail.original	string?	原始图片 URL
pictures.results	object[]?	其他图片（src、original）
profiles	object[]?	外部个人资料（name、url、long_name、img）
timezone	string?	IANA 时区（例如，America/Los_Angeles）
zoom_level	int	建议的地图缩放级别（默认值为 7）

地理地点字段（cities、countries、regions、neighborhoods）

这四个分类共用一种结构，仅 type 标识符不同。已发布的规范将它们命名为 CityResult / CountryResult / RegionResult / NeighborhoodResult。

字段	类型	描述
type	string	分类标识符：city、country、region 或 neighborhood
name	string	地点名称
country	string	地点的国家代码
coordinates	[float, float]	[latitude, longitude]
thumbnail.src	string	主图片 URL

AddressResult 字段（addresses 和 streets）

这两个类别使用相同的模型。addresses 中的项类型为 type: "address"（街道 + 门牌号）；streets 中的项类型为 type: "street"（整条街道）。

字段	类型	描述
type	string	"address"（在 addresses 中）或 "street"（在 streets 中）
name	string	地址或街道的显示名称
coordinates	[float, float]	[latitude, longitude]
pois	object[]	位于此地址/街道上的 LocationResult 对象
pois_nearby	object[]	位于附近的 LocationResult 对象
zoom_level	int	建议的地图缩放级别（默认值为 15）
distance.value	float?	与搜索位置之间的距离
distance.units	string?	距离单位
postal_address	object?	displayAddress、streetAddress、addressLocality、addressRegion、country

混合排序（mixed）

mixed 是一个有序的 ResultReference 对象列表，告知客户端如何将不同类别中的项交错排列在同一个 SERP 上。

字段	类型	描述
type	string	要从中提取内容的类别：results、cities、countries、regions、neighborhoods、addresses 或 streets
index	int?	此类别中项的从 0 开始的索引。当 all 为 true 时，可以为 null
all	bool	为 true 时，应在此位置放置指定类别中所有剩余项

只渲染 POI 的客户端可以完全忽略 mixed，直接读取 results。

响应示例

{
  "type": "locations",
  "results": [
    {
      "type": "location_result",
      "title": "Blue Bottle Coffee",
      "url": "https://yelp.com/biz/blue-bottle-coffee-sf",
      "provider_url": "",
      "id": "loc4CQWMJWLD4VBEBZ62XQLJTGK6YCJEEJDNAAAAAAA=",
      "description": "Coffee Shop",
      "postal_address": {
        "type": "PostalAddress",
        "displayAddress": "315 Linden St, San Francisco, CA 94102"
      },
      "contact": { "telephone": "+15106533394" },
      "rating": {
        "ratingValue": 4.3,
        "bestRating": 5.0,
        "reviewCount": 1024,
        "is_tripadvisor": true
      },
      "opening_hours": {
        "current_day": [
          { "abbr_name": "Tue", "full_name": "Tuesday", "opens": "07:00", "closes": "18:00" }
        ],
        "days": [
          [{ "abbr_name": "Mon", "full_name": "Monday", "opens": "07:00", "closes": "18:00" }]
        ]
      },
      "coordinates": [37.7763, -122.4215],
      "categories": [],
      "serves_cuisine": ["Cafe", "Coffee Shop"],
      "price_range": "$$",
      "icon_category": "cafe",
      "thumbnail": {
        "src": "https://example.com/thumb.jpg",
        "original": "https://example.com/original.jpg"
      },
      "zoom_level": 7
    }
  ],
  "cities": [],
  "countries": [],
  "regions": [],
  "neighborhoods": [],
  "addresses": [],
  "streets": [],
  "mixed": [
    { "type": "results", "index": 0, "all": false }
  ],
  "location": {
    "coordinates": [37.7749, -122.4194],
    "name": "San Francisco",
    "country": "US"
  }
}

对于匹配城市名称的查询，响应还会在 cities 中提供一个城市条目：

{
  "cities": [
    {
      "type": "city",
      "name": "San Francisco",
      "country": "US",
      "coordinates": [37.7749, -122.4194],
      "thumbnail": { "src": "https://example.com/sf.jpg" }
    }
  ],
  "mixed": [
    { "type": "cities", "index": 0, "all": false }
  ]
}

使用 POI 详情和描述丰富搜索结果

可以将 results 中的 POI id 值传递给同级端点，以获取更丰富的数据：

# Get full POI details (hours, reviews, photos, web result mentions)
curl -s "https://api.search.brave.com/res/v1/local/pois" -G \
  --data-urlencode "ids=loc4CQWMJWLD4VBEBZ62XQLJTGK6YCJEEJDNAAAAAAA=" \
  -H "X-Subscription-Token: ${BRAVE_SEARCH_API_KEY}"

# Get AI-generated descriptions
curl -s "https://api.search.brave.com/res/v1/local/descriptions" -G \
  --data-urlencode "ids=loc4CQWMJWLD4VBEBZ62XQLJTGK6YCJEEJDNAAAAAAA=" \
  -H "X-Subscription-Token: ${BRAVE_SEARCH_API_KEY}"

使用场景

• 基于地图的探索：使用坐标 + 半径搜索地图可见视口内的 POI。无需预先提供查询。
• 位置感知应用：构建“附近”功能——传入设备的 GPS 坐标和查询，以查找相关商家。
• 旅行规划：使用位置字符串（例如 paris france）搜索景点、餐厅和酒店，无需提供精确坐标。

注意事项

• 查找地点，而非网页：此端点搜索的是实体地点的地理索引。常规信息检索请使用网页搜索。
• 选择半径：较小的半径（低于约 20 km）会提供更聚焦的结果。增大半径可覆盖更远的特定或知名地点；对于常见类别搜索（例如 restaurants），使用默认偏置或较小的半径效果最佳。