Brave Web Search

Brave Web Search

Wraps the Brave Web Search endpoint (/res/v1/web/search). Returns ranked search results with rich structured data.

Auth via BRAVE_SEARCH_API_KEY (Search plan). Subscribe at https://api-dashboard.search.brave.com/app/subscriptions/subscribe.

Quick Start

Single query:

python skills/brave-web-search/scripts/search.py \
  --query "rust programming tutorials" \
  --output output/brave_web.json

With filters:

python skills/brave-web-search/scripts/search.py \
  --query "site:moz.com schema markup" \
  --country DE --search-lang de \
  --count 20 --freshness pm \
  --safesearch moderate \
  --output results.json

Goggles re-ranking (allow-list):

python skills/brave-web-search/scripts/search.py \
  --query "react hooks best practices" \
  --goggles '$discard
$site=react.dev
$site=developer.mozilla.org' \
  --output results.json

Parameters

Search Operators

Standard operators work in --query: site:, intitle:, inbody:, inpage:, ext:, filetype:, lang:, loc:, +term, -term, "exact", AND, OR, NOT. Disable with --no-operators.

Goggles (Brave-only re-ranking)

Goggles let you boost or discard sources. Two methods:

• Hosted: Pass a public URL to a .goggle file (must be on GitHub/GitLab and registered at https://search.brave.com/goggles/create).
• Inline: Pass rules directly. Syntax: $boost=N/$downrank=N (1-10), $discard, $site=domain. Combine with commas, separate rules with newlines.

Common patterns:

# Allow-list
$discard
$site=docs.python.org
$site=developer.mozilla.org

# Block-list
$discard,site=pinterest.com
$discard,site=quora.com

Rich Callbacks (weather, stocks, sports, etc.)

For queries like "weather san francisco" or "AAPL stock", enable --enable-rich-callback. The response rich.hint.callback_key can then be passed to the rich endpoint:

python skills/brave-web-search/scripts/search.py \
  --rich-callback-key abc123hex \
  --output output/rich.json

Supported verticals: Calculator, Definitions, Unit Conversion, Stocks, Currency, Cryptocurrency, Weather, Sports (American Football, Baseball, Basketball, Cricket, Football/Soccer, Ice Hockey), Web3, Translator, Package Tracker, Unix Timestamp.

Response Shape

Top-level fields: type, query, web.results[], news.results[], videos.results[], discussions.results[], faq.results[], infobox.results[], locations.results[], mixed, rich.

Each web.results[] entry contains: title, url, description, age, language, meta_url, thumbnail, extra_snippets, deep_results, page_age, plus type-specific blocks (product, recipe, article, book, software, rating, faq, movie, video, location, qa, creative_work, music_recording, organization, review).

mixed defines the preferred display order across types (main, top, side arrays of {type, index, all}).

Notes

• Pagination: --offset accepts 0-9. Combine with --count (max 20).
• Country ALL: Returns global results; otherwise localized to the 2-letter code.
• Plan: This endpoint is on the Search plan. Answers/research mode is on the Answers plan and uses BRAVE_ANSWERS_API_KEY (see brave-answers skill).