Brave Search API Skills

The Local Place Search endpoint is designed to search a geographic index of physical places. It is optimized for finding locations rather than general web pages.

Common Use Cases:

• Map-based exploration: Search for POIs within a visible map viewport using coordinates and a radius. This can be done without a prior text query.
• Location-aware apps: Implement "nearby" features by passing device GPS coordinates and a query to find relevant businesses.
• Travel planning: Search for attractions, restaurants, and hotels using a location string (e.g., paris france) without needing exact coordinates.

Best Practices:

• Choosing a radius: Use a tighter radius (below ~20 km) for more focused results. For common category searches like restaurants, a tighter radius or the default bias usually works best. Increase the radius to reach specific or well-known places further away.

The local-place-search skill allows you to find physical locations such as businesses, Points of Interest (POIs), street addresses, cities, and streets.

Key Characteristics:

• Standalone: Unlike local-pois or local-descriptions, you do not need prior POI IDs. You can search directly using a query and a location.
• Rich Data: Results include addresses, coordinates, ratings, opening hours, and phone numbers, reducing the need for follow-up calls.
• Flexible Locating: You can search by coordinates (latitude and longitude), a location string, or omit both to search globally (though providing a location is recommended for precision).
• Browsing: If you omit the query parameter q, the API returns general POIs for the specified area.

Requirements:

• API Key: Required via the X-Subscription-Token header.
• Plan: Included in the Search plan.

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"

Goggles allow you to control which sources ground your LLM, which is essential for high-quality RAG. You can use Hosted goggles (via URL) or Inline goggles (via query parameter).

Syntax: Rules start with $ followed by comma-separated options.

• Actions: discard, boost[=N], downrank[=N] (N is 1–10).
• Site filter: site=DOMAIN.
• Separator: Separate rules with \n (newline).

Common Patterns:

• Official docs only: $discard\n$site=docs.python.org
• Exclude user content: $discard,site=reddit.com\n$discard,site=stackoverflow.com
• Academic sources: $discard\n$site=arxiv.org\n$site=scholar.google.com
• Allow list: $discard\n$site=docs.python.org\n$site=developer.mozilla.org
• Block list: $discard,site=pinterest.com\n$discard,site=quora.com

# Example: Inline Goggles
curl -s "https://api.search.brave.com/res/v1/llm/context" \
  -H "Accept: application/json" \
  -H "X-Subscription-Token: ${BRAVE_SEARCH_API_KEY}" \
  -G \
  --data-urlencode "q=rust programming" \
  --data-urlencode 'goggles=$discard\n$site=docs.rs\n$site=rust-lang.org'

The response is a JSON object containing metadata about the query and categorized results.

Key sections include:

• query: Details about the original, altered, and cleaned query.
• web: The primary results array containing title, url, description, thumbnail, and specialized objects like product, recipe, article, book, software, faq, movie, video, location, qa, etc.
• mixed: An object defining the preferred display order using main, top, and side arrays containing ResultReference objects.
• Specialized result arrays: discussions, faq, news, videos, infobox, locations.

{
  "type": "search",
  "query": {
    "original": "python frameworks",
    "altered": "python web frameworks",
    "spellcheck_off": false,
    "more_results_available": true
  },
  "web": {
    "type": "search",
    "results": [
      {
        "title": "Top Python Web Frameworks",
        "url": "https://example.com/python-frameworks",
        "description": "A comprehensive guide to Python web frameworks...",
        "age": "2 days ago",
        "language": "en",
        "meta_url": {
          "scheme": "https",
          "netloc": "example.com",
          "hostname": "example.com",
          "path": "/python-frameworks"
        },
        "thumbnail": {
          "src": "https://...",
          "original": "https://original-image-url.com/img.jpg"
        },
        "extra_snippets": ["Additional excerpt 1...", "Additional excerpt 2..."]
      }
    ],
    "family_friendly": true
  },
  "mixed": {
    "type": "mixed",
    "main": [
      {"type": "web", "index": 0, "all": false},
      {"type": "web", "index": 1, "all": false},
      {"type": "videos", "all": true}
    ],
    "top": [],
    "side": []
  }
}

Goggles allow you to control which sources appear in results by boosting, demoting, or discarding domains. This is supported on context, web, and news commands.

Domain Shortcuts

Note: --include-site, --exclude-site, and --goggles are mutually exclusive.

• Allowlist: bx "query" --include-site docs.rs --include-site github.com
• Blocklist: bx "query" --exclude-site example.com

Inline Goggle Rules (DSL)

Rules are separated by newlines. Use the following syntax:

Example: Boosting official docs and demoting blogs

bx "axum middleware tower" \
  --goggles '$boost=5,site=docs.rs
$boost=3,site=github.com
/docs/$boost=5
/blog/$downrank=3' --max-tokens 4096

Example: Using a file for rules

bx "query" --goggles @/path/to/rules.txt

Example: Piping rules via stdin

echo '$boost=5,site=docs.rs' | bx "query" --goggles @-

Control location-aware results using the enable_local parameter and location headers.

enable_local values:

• null (default): Auto-detect — enabled when any location header is provided.
• true: Force local — always use local recall.
• false: Force standard — always use standard web ranking.

Location Headers: Use these headers to provide location context. X-Loc-Lat and X-Loc-Long take precedence over text-based headers.

# Example: With Coordinates
curl -s "https://api.search.brave.com/res/v1/llm/context" \
  -H "Accept: application/json" \
  -H "X-Subscription-Token: ${BRAVE_SEARCH_API_KEY}" \
  -H "X-Loc-Lat: 37.7749" \
  -H "X-Loc-Long: -122.4194" \
  -G \
  --data-urlencode "q=best coffee shops near me"