# Brave Web Search

> Run web searches via Brave Search API. Returns ranked results with titles, URLs, snippets, thumbnails, and rich types (web, news, videos, discussions, FAQ, infobox, locations). Supports freshness filters, SafeSearch, Goggles re-ranking, location-aware results, pagination. Use for real-time web search results or SERP-style data. For RAG use brave-llm-context; for synthesized answers use brave-answers.

- Skill: `buzzmatic/brave-web-search` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add buzzmatic/brave-web-search`
- Raw SKILL.md: https://api.skillmd.com/api/skills/buzzmatic/brave-web-search/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: Buzzmatic (https://skillmd.com/u/buzzmatic)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/buzzmatic/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:**
```bash
python skills/brave-web-search/scripts/search.py \
  --query "rust programming tutorials" \
  --output output/brave_web.json
```

**With filters:**
```bash
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):**
```bash
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

| Flag | Maps to | Notes |
|---|---|---|
| `--query / -q` | `q` | Required. 1-400 chars, max 50 words. |
| `--country` | `country` | 2-letter code or `ALL`. Default `US`. |
| `--search-lang` | `search_lang` | Language code (`en`, `de`, ...). Default `en`. |
| `--ui-lang` | `ui_lang` | UI locale (`en-US`). |
| `--count` | `count` | 1-20. Default `20`. |
| `--offset` | `offset` | 0-9 for pagination. |
| `--safesearch` | `safesearch` | `off` / `moderate` (default) / `strict`. |
| `--freshness` | `freshness` | `pd` / `pw` / `pm` / `py` or `YYYY-MM-DDtoYYYY-MM-DD`. |
| `--result-filter` | `result_filter` | Comma-separated: `web,videos,news,discussions,faq,infobox,locations`. |
| `--goggles` | `goggles` | URL to a hosted Goggle, or inline rules (newline-separated). |
| `--extra-snippets` | `extra_snippets` | `true` to add up to 5 extra snippets per result. |
| `--no-spellcheck` | `spellcheck=false` | Disable auto-correct. |
| `--no-operators` | `operators=false` | Disable search operators. |
| `--units` | `units` | `metric` / `imperial`. |
| `--enable-rich-callback` | `enable_rich_callback` | Returns `rich.hint.callback_key` for stocks/weather/sports/etc. |
| `--include-fetch-metadata` | `include_fetch_metadata` | Adds `fetched_content_timestamp` to each result. |
| `--loc-lat` / `--loc-long` | `X-Loc-Lat` / `X-Loc-Long` | Coordinates take priority for location-aware results. |
| `--loc-city` / `--loc-state` / `--loc-country` / `--loc-postal` | `X-Loc-*` headers | Used only if no coordinates. |
| `--rich-callback-key` | n/a | Fetch rich enrichment data (`/res/v1/web/rich`) using callback key from a previous response. |

## 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:

```bash
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).