# Brave Search

> Brave Search API for web search with region-specific and localized results.

- Skill: `junsuzuki1973/brave-search` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add junsuzuki1973/brave-search`
- Raw SKILL.md: https://api.skillmd.com/api/skills/junsuzuki1973/brave-search/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: JunSuzuki1973 (https://skillmd.com/u/junsuzuki1973)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/junsuzuki1973/brave-search

---


# Brave Search API

Brave Search API provides fast, privacy-focused web search with region-specific and localized results.

## Configuration

API credentials are stored in `~/.clawdbot/brave-search-config.json`:
```json
{
  "apiKey": "your_brave_search_api_key_here"
}
```

## API Endpoint

**Base URL:** `https://api.search.brave.com/res/v1/web/search`

### Search Query

```bash
curl -X GET 'https://api.search.brave.com/res/v1/web/search?q={query}' \
  -H 'Accept: application/json' \
  -H 'Accept-Encoding: gzip' \
  -H 'X-Subscription-Token: {apiKey}'
```

## Query Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `q` | string | Yes | Search query string |
| `count` | integer | No | Number of results (1-20, default: 20) |
| `offset` | integer | No | Pagination offset (default: 0) |
| `country` | string | No | 2-letter country code (e.g., JP, US, GB, DE) |
| `search_lang` | string | No | ISO language code for search results (e.g., ja, en, de) |
| `ui_lang` | string | No | ISO language code for UI elements |
| `safesearch` | string | No | strict, moderate, or off (default: moderate) |
| `freshness` | string | No | pd, pw, pm, py (past day/week/month/year) or date range |
| `text_decorations` | boolean | No | Enable bolding of query terms (default: true) |
| `spellcheck` | boolean | No | Enable spellcheck (default: true) |
| `result_filter` | string | No | Filter results (web, news, images, videos) |
| `units` | string | No | Distance units (km, mi) |

## Response Format

```json
{
  "web": {
    "results": [
      {
        "title": "Page Title",
        "url": "https://example.com",
        "description": "Page description...",
        "published": "2025-12-30T00:00:00+00:00",
        "author": ["Author Name"],
        "type": "web"
      }
    ]
  },
  "query": {
    "original": "search query",
    "cleaned": "search query"
  },
  "results_count": 1000000
}
```

## Usage Examples

### Basic Search
```bash
curl -X GET 'https://api.search.brave.com/res/v1/search?q=AI%20agents' \
  -H 'X-Subscription-Token: {apiKey}' \
  | jq '.web.results[] | {title, url}'
```

### Japanese Results with Country Filter
```bash
curl -X GET 'https://api.search.brave.com/res/v1/search?q=AIエージェント&country=JP&search_lang=ja&ui_lang=ja' \
  -H 'X-Subscription-Token: {apiKey}' \
  | jq '.web.results[]'
```

### Recent News (Past Week)
```bash
curl -X GET 'https://api.search.brave.com/res/v1/search?q=OpenAI&freshness=pw&result_filter=news' \
  -H 'X-Subscription-Token: {apiKey}' \
  | jq '.web.results[]'
```

### Limited Results
```bash
curl -X GET 'https://api.search.brave.com/res/v1/search?q=Python%20programming&count=5' \
  -H 'X-Subscription-Token: {apiKey}' \
  | jq '.web.results[:3]'
```

### Date Range Filter
```bash
curl -X GET 'https://api.search.brave.com/res/v1/search?q=AI%20research&freshness=2025-01-01to2025-12-31' \
  -H 'X-Subscription-Token: {apiKey}' \
  | jq '.web.results[]'
```

## Helper Scripts

### Quick Search
```bash
#!/bin/bash
# ~/.openclaw/workspace/skills/brave-search/scripts/search.sh

API_KEY=$(cat ~/.clawdbot/brave-search-config.json | jq -r '.apiKey')
QUERY="$1"

curl -s -X GET "https://api.search.brave.com/res/v1/search?q=$(printf '%s' "$QUERY" | jq -sRr @uri)" \
  -H "X-Subscription-Token: $API_KEY" \
  | jq '.web.results[] | {title, url}'
```

### Japanese Search
```bash
#!/bin/bash
# ~/.openclaw/workspace/skills/brave-search/scripts/search_ja.sh

API_KEY=$(cat ~/.clawdbot/brave-search-config.json | jq -r '.apiKey')
QUERY="$1"

curl -s -X GET "https://api.search.brave.com/res/v1/search?q=$(printf '%s' "$QUERY" | jq -sRr @uri)&country=JP&search_lang=ja&ui_lang=ja" \
  -H "X-Subscription-Token: $API_KEY" \
  | jq '.web.results[]'
```

## Country Codes

Common country codes:
- `JP` - Japan
- `US` - United States
- `GB` - United Kingdom
- `DE` - Germany
- `FR` - France
- `ALL` - All countries (default)

## Language Codes

Common language codes:
- `ja` - Japanese
- `en` - English
- `de` - German
- `fr` - French
- `es` - Spanish

## Freshness Values

- `pd` - Past day (past 24 hours)
- `pw` - Past week
- `pm` - Past month
- `py` - Past year
- `YYYY-MM-DDtoYYYY-MM-DD` - Date range

## Result Filters

- `web` - Web results (default)
- `news` - News articles
- `images` - Image search
- `videos` - Video search

## Rate Limits

- Free tier: 2,000 requests per month
- Check subscription for current limits

## Notes

- Always include `X-Subscription-Token` header with API key
- URL-encode query parameters
- Use `jq` for JSON parsing
- The API returns gzip-encoded responses by default
- Results include title, URL, description, and metadata