Back to Details

local-pois

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Local POIs (Search API)

本地POI（搜索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.
  1. Call 
    web-search
    with 
    result_filter=locations
    to get POI IDs from 
    locations.results[].id
  2. Pass those IDs to this endpoint to get full business details
需要API Key：可前往https://api.search.brave.com获取
适用套餐：包含在搜索套餐中。详情请见https://api-dashboard.search.brave.com/app/subscriptions/subscribe
两步流程：此接口需要先通过网页搜索获取POI ID。
  1. 调用
    web-search
    接口并设置
    result_filter=locations
    ，从
    locations.results[].id
    中获取POI ID
  2. 将这些ID传入此接口，获取完整的商家详情

Quick Start (cURL)

快速开始（cURL）

Get POI Details

获取POI详情

bash
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="
bash
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="

Multiple POIs with Location Headers

多POI查询（带位置请求头）

bash
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"
Note: POI IDs are opaque strings returned in web search 
locations.results[].id
. IDs are ephemeral and expire after ~8 hours. The example IDs above are for illustration — fetch fresh IDs via 
web-search
with 
result_filter=locations
. Use 
--data-urlencode
since IDs may contain 
=
.
bash
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"
注意：POI ID是网页搜索
locations.results[].id
返回的不透明字符串，有效期约8小时后过期。以上示例ID仅作演示，请通过设置
result_filter=locations
的
web-search
接口获取最新ID。由于ID可能包含
=
符号，请使用
--data-urlencode
进行编码。

Endpoint

接口地址

http
GET https://api.search.brave.com/res/v1/local/pois
Authentication: 
X-Subscription-Token: <API_KEY>
header
http
GET https://api.search.brave.com/res/v1/local/pois
身份验证：需携带
X-Subscription-Token: <API_KEY>
请求头

Parameters

请求参数

ParameterTypeRequiredDefaultDescription
ids
string[]Yes—POI IDs from web search results (1-20)
search_lang
stringNo
en
Language preference (2+ char language code)
ui_lang
stringNo
en-US
UI language (locale code, e.g., "en-US")
units
stringNonull
metric
(km) or 
imperial
(miles)
参数类型是否必填默认值说明
ids
string[]是—来自网页搜索结果的POI ID（1-20个）
search_lang
string否
en
搜索语言偏好（2位及以上字符的语言代码）
ui_lang
string否
en-US
UI语言（区域代码，例如"en-US"）
units
string否null单位体系：
metric
（公里）或
imperial
（英里）

Location Headers (Optional)

可选位置请求头

For distance calculation from user location:
HeaderTypeRangeDescription
X-Loc-Lat
float-90.0 to 90.0User latitude
X-Loc-Long
float-180.0 to 180.0User longitude
用于计算与用户位置的距离：
请求头类型范围说明
X-Loc-Lat
float-90.0 至 90.0用户纬度
X-Loc-Long
float-180.0 至 180.0用户经度

Response Fields

响应字段

The response has 
type: "local_pois"
and a 
results
array of 
LocationResult
objects:
FieldTypeDescription
title
stringBusiness/POI name
url
stringCanonical URL for the location
provider_url
stringProvider page URL
type
stringAlways 
"location_result"
id
stringPOI identifier (opaque string, valid ~8 hours)
description
string?Short description
postal_address.type
stringAlways 
"PostalAddress"
postal_address.displayAddress
stringFormatted display address
postal_address.streetAddress
string?Street address
postal_address.addressLocality
string?City
postal_address.addressRegion
string?State/region
postal_address.postalCode
string?Postal/ZIP code
postal_address.country
string?Country code
contact.telephone
string?Phone number
contact.email
string?Email address
rating.ratingValue
float?Average rating (≥0)
rating.bestRating
float?Max possible rating
rating.reviewCount
int?Number of reviews
rating.profile.name
string?Rating provider name
rating.profile.url
string?Rating provider URL
opening_hours.current_day
object[]?Today's hours (
abbr_name
, 
full_name
, 
opens
, 
closes
)
opening_hours.days
object[][]?Hours for each day of the week (same structure)
coordinates
[float, float]?
[latitude, longitude]
tuple
distance.value
float?Distance from user location
distance.units
string?Distance unit (
km
or 
miles
)
categories
string[]Business categories (default 
[]
)
price_range
string?Price indicator (
$
, 
$$
, 
$$$
, 
$$$$
)
serves_cuisine
string[]?Cuisine types (restaurants)
thumbnail.src
string?Thumbnail image URL
thumbnail.original
string?Original image URL
profiles
object[]?External profiles (
name
, 
url
, 
long_name
, 
img
)
reviews.reviews_in_foreign_language
boolWhether reviews in a foreign language are available
pictures.results
object[]?Photo thumbnails
action
object?Action to take — has 
type
(string) and 
url
(string)
results
object[]?Related web results (
LocationWebResult
with 
meta_url
)
timezone
string?IANA timezone (e.g., 
America/Los_Angeles
)
timezone_offset
int?UTC timezone offset
响应的
type
为
"local_pois"
，包含一个由
LocationResult
对象组成的
results
数组：
字段类型说明
title
string商家/POI名称
url
string位置的标准URL
provider_url
string提供方页面URL
type
string固定为
"location_result"
id
stringPOI标识符（不透明字符串，有效期约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?邮政编码
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]?
[纬度, 经度]
数组
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
（字符串）和
url
（字符串）字段
results
object[]?相关网页结果（
LocationWebResult
类型，包含
meta_url
字段）
timezone
string?IANA时区（例如
America/Los_Angeles
）
timezone_offset
int?UTC时区偏移量

Example Response

响应示例

json
{
  "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"
    }
  ]
}
json
{
  "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"
    }
  ]
}

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
的网页搜索API（
web-search
）：
bash
undefined

1. Search for local businesses

1. 搜索本地商家

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"
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

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

3. Use those IDs with this endpoint

3. 将这些ID传入本接口使用

undefined
undefined

Use Cases

适用场景

  • Local business lookup: Retrieve full details (hours, contact, address) for POIs surfaced in web search
  • Restaurant discovery pipeline: Search for restaurants, fetch POI details, filter by cuisine/rating/price_range
  • Business hours checker: Get opening_hours for a business to determine if currently open
  • Location-aware application: Combine with location headers to get distance calculations for nearby POIs
  • 本地商家查询：获取网页搜索中出现的POI的完整详情（营业时间、联系方式、地址等）
  • 餐厅发现流程：搜索餐厅、获取POI详情、按菜系/评分/价格区间筛选
  • 商家营业时间查询：获取商家的营业时间，判断当前是否营业
  • 位置感知应用：结合位置请求头，计算附近POI与用户的距离

Notes

注意事项

  • ID format: Opaque strings (use 
    --data-urlencode
    for cURL)
  • Units: 
    metric
    or 
    imperial
    for distance measurement preference
  • Max IDs: Up to 20 IDs per request
  • ID格式：不透明字符串（在cURL中请使用
    --data-urlencode
    ）
  • 单位：距离测量偏好可选择
    metric
    或
    imperial
  • 最大ID数量：每次请求最多支持20个ID