tomevault-io Local POIs (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-searchwithresult_filter=locationsto get POI IDs fromlocations.results[].id- Pass those IDs to this endpoint to get full business details
Quick Start (cURL)
Get POI Details
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
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 =.
Endpoint
GET https://api.search.brave.com/res/v1/local/pois
Authentication: X-Subscription-Token: <API_KEY> header
Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
ids |
string[] | Yes | — | POI IDs from web search results (1-20) |
search_lang |
string | No | en |
Language preference (2+ char language code) |
ui_lang |
string | No | en-US |
UI language (locale code, e.g., "en-US") |
units |
string | No | null | metric (km) or imperial (miles) |
Location Headers (Optional)
For distance calculation from user location:
| Header | Type | Range | Description |
|---|---|---|---|
X-Loc-Lat |
float | -90.0 to 90.0 | User latitude |
X-Loc-Long |
float | -180.0 to 180.0 | User longitude |
Response Fields
The response has type: "local_pois" and a results array of LocationResult objects:
| Field | Type | Description |
|---|---|---|
title |
string | Business/POI name |
url |
string | Canonical URL for the location |
provider_url |
string | Provider page URL |
type |
string | Always "location_result" |
id |
string | POI identifier (opaque string, valid ~8 hours) |
description |
string? | Short description |
postal_address.type |
string | Always "PostalAddress" |
postal_address.displayAddress |
string | Formatted 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 |
bool | Whether 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 |
Example Response
{
"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 IDs come from the Web Search API (web-search) with 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
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
Notes
- ID format: Opaque strings (use
--data-urlencodefor cURL) - Units:
metricorimperialfor distance measurement preference - Max IDs: Up to 20 IDs per request
Converted and distributed by TomeVault — claim your Tome and manage your conversions.