local-pois

ローカルの POI（検索 API）

API キーが必要です：https://api.search.brave.com で取得してください。

プラン：Search プランに含まれています。https://api-dashboard.search.brave.com/app/subscriptions/subscribe をご覧ください。

2 段階のフロー：このエンドポイントを使用するには、事前の検索で POI ID を取得する必要があります。

1. local-place-search、または result_filter=locations を指定した web-search（locations.results[].id）から POI ID を取得します。
2. それらの ID をこのエンドポイントに渡して、店舗の詳細情報を取得します。

クイックスタート（cURL）

POI の詳細を取得

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

位置情報ヘッダーを指定して複数の POI を取得

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 で返される不透明な文字列です。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[]	はい	—	ウェブ検索結果から取得した POI ID（1～20 個）
search_lang	string	いいえ	en	言語設定（2 文字以上の言語コード）
ui_lang	string	いいえ	en-US	UI 言語（ロケールコード、例：「en-US」）
units	string	いいえ	null	metric（km）または imperial（マイル）

位置情報ヘッダー（任意）

ユーザーの位置情報を基準に距離を計算する場合：

ヘッダー	型	範囲	説明
X-Loc-Lat	float	-90.0～90.0	ユーザーの緯度
X-Loc-Long	float	-180.0～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?	郵便番号
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[][]?	1週間分の各曜日の営業時間（同じ構造）
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 を直接返します。POI ID は、result_filter=locations を指定した Web Search API（web-search）からも取得できます。

# 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 の詳細情報を取得して、料理の種類、評価、価格帯で絞り込みます
• 営業時間の確認：事業者の opening_hours を取得し、現在営業中かどうかを判断します
• 位置情報を活用するアプリケーション：位置情報ヘッダーと組み合わせて、近隣の POI までの距離を計算します

注意事項

• ID 形式：不透明な文字列です（cURL では --data-urlencode を使用してください）
• 単位：距離の測定方法の設定には metric または imperial を指定します
• ID の最大数：1 リクエストにつき最大 20 個の ID を指定できます