local-pois

本地地点（Search API）

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

套餐：包含在 Search 套餐中。请参阅 https://api-dashboard.search.brave.com/app/subscriptions/subscribe

两步流程：此端点需要先通过搜索获取地点 ID。

1. 从 local-place-search 获取地点 ID，或通过设置 result_filter=locations 使用 web-search 获取（locations.results[].id）
2. 将这些 ID 传递给此端点，以获取完整的商家详情

快速入门（cURL）

获取地点详情

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

使用位置标头查询多个地点

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

注意：地点 ID 是在网页搜索的 locations.results[].id 中返回的不透明字符串。ID 是临时的，约 8 小时后会过期。以上示例中的 ID 仅供说明——请通过设置 result_filter=locations 使用 web-search 获取新的 ID。由于 ID 可能包含 =，请使用 --data-urlencode。

端点

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

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

参数

参数	类型	必填	默认值	说明
ids	string[]	是	—	网页搜索结果中的地点 ID（1-20 个）
search_lang	string	否	en	语言偏好（至少 2 个字符的语言代码）
ui_lang	string	否	en-US	界面语言（区域设置代码，例如 “en-US”）
units	string	否	null	metric（公里）或 imperial（英里）

位置标头（可选）

用于计算与用户位置之间的距离：

标头	类型	范围	说明
X-Loc-Lat	float	-90.0 to 90.0	用户纬度
X-Loc-Long	float	-180.0 to 180.0	用户经度

响应字段

响应包含 type: "local_pois" 和一个由 LocationResult 对象组成的 results 数组：

字段	类型	描述
title	string	商家/POI 名称
url	string	该位置的规范 URL
provider_url	string	提供商页面 URL
type	string	始终为 "location_result"
id	string	POI 标识符（不透明字符串，有效期约 8 小时）
description	string?	简短描述
postal_address.type	string	始终为 "PostalAddress"
postal_address.displayAddress	string	格式化的显示地址
postal_address.streetAddress	string?	街道地址
postal_address.addressLocality	string?	城市
postal_address.addressRegion	string?	州/地区
postal_address.postalCode	string?	邮政编码/ZIP 代码
postal_address.country	string?	国家/地区代码
contact.telephone	string?	电话号码
contact.email	string?	电子邮箱地址
rating.ratingValue	float?	平均评分（≥0）
rating.bestRating	float?	最高可能评分
rating.reviewCount	int?	评论数量
rating.profile.name	string?	评分提供商名称
rating.profile.url	string?	评分提供商 URL
opening_hours.current_day	object[]?	今天的营业时间（abbr_name、full_name、opens、closes）
opening_hours.days	object[][]?	一周中每天的营业时间（结构相同）
coordinates	[float, float]?	[latitude, longitude] 坐标组
distance.value	float?	与用户位置的距离
distance.units	string?	距离单位（km 或 miles）
categories	string[]	商家类别（默认为 []）
price_range	string?	价格标示（$、$$、$$$、$$$$）
serves_cuisine	string[]?	菜系类型（餐厅）
thumbnail.src	string?	缩略图 URL
thumbnail.original	string?	原始图片 URL
profiles	object[]?	外部资料（name、url、long_name、img）
reviews.reviews_in_foreign_language	bool	是否提供外语评论
pictures.results	object[]?	照片缩略图
action	object?	要执行的操作——包含 type（string）和 url（string）
results	object[]?	相关网页结果（带有 meta_url 的 LocationWebResult）
timezone	string?	IANA 时区（例如，America/Los_Angeles）
timezone_offset	int?	UTC 时区偏移量

响应示例

{
  "type": "local_pois",
  "results": [
    {
      "type": "location_result",
      "title": "Park Mediterranean Grill",
      "url": "https://yelp.com/biz/park-mediterranean-grill-sf",
      "provider_url": "https://yelp.com/biz/park-mediterranean-grill-sf",
      "id": "loc4CQWMJWLD4VBEBZ62XQLJTGK6YCJEEJDNAAAAAAA=",
      "postal_address": {
        "type": "PostalAddress",
        "displayAddress": "123 Main St, San Francisco, CA 94102",
        "streetAddress": "123 Main St",
        "addressLocality": "San Francisco",
        "addressRegion": "CA",
        "postalCode": "94102",
        "country": "US"
      },
      "contact": { "telephone": "+1 415-555-0123" },
      "thumbnail": {
        "src": "https://example.com/thumb.jpg",
        "original": "https://example.com/original.jpg"
      },
      "rating": {
        "ratingValue": 4.5,
        "bestRating": 5.0,
        "reviewCount": 234,
      },
      "opening_hours": {
        "current_day": [
          { "abbr_name": "Mon", "full_name": "Monday", "opens": "07:00", "closes": "21:00" }
        ]
      },
      "coordinates": [37.7749, -122.4194],
      "distance": { "value": 0.3, "units": "miles" },
      "categories": ["Mediterranean", "Greek"],
      "price_range": "$$",
      "serves_cuisine": ["Mediterranean", "Greek"],
      "timezone": "America/Los_Angeles"
    }
  ]
}

获取 POI ID

local-place-search 会直接返回 POI ID。它们也可以来自网页搜索 API（web-search），并使用 result_filter=locations：

# 1. Search for local businesses
curl -s "https://api.search.brave.com/res/v1/web/search?q=coffee+shops+near+me&result_filter=locations" \
  -H "Accept: application/json" \
  -H "X-Subscription-Token: ${BRAVE_SEARCH_API_KEY}" \
  -H "X-Loc-Lat: 37.7749" \
  -H "X-Loc-Long: -122.4194"

# 2. Extract POI IDs from locations.results[].id
# 3. Use those IDs with this endpoint

使用场景

• 本地商家查询：获取网页搜索中出现的 POI 的完整详情（营业时间、联系方式、地址）
• 餐厅发现流程：搜索餐厅、获取 POI 详情，并按菜系/评分/price_range 筛选
• 商家营业时间查询：获取商家的 opening_hours，以确定当前是否营业
• 位置感知应用：结合位置标头，计算附近 POI 的距离

注意事项

• ID 格式：不透明字符串（cURL 请使用 --data-urlencode）
• 单位：距离测量偏好可设为 metric 或 imperial
• ID 数量上限：每个请求最多 20 个