Brave Search API Wrapper

0.2.0 verified Sat May 09 auth: no python

A Python wrapper for the Brave Search API that provides convenient access to Brave's privacy-preserving search endpoints. Current version 0.2.0, compatible with Python 3.8-3.12. Active development with monthly releases.

pip install brave-search

Common errors

error ModuleNotFoundError: No module named 'brave_search' ↓

cause The import module name is 'brave', not 'brave_search'. The PyPI package is 'brave-search'.

fix

Install with 'pip install brave-search' and import as 'from brave import Brave'.

error brave.exceptions.BraveAPIException: API key not provided. Please set BRAVE_API_KEY environment variable. ↓

cause The library requires a Brave Search API key, which must be provided either via environment variable or constructor argument.

fix

Set 'BRAVE_API_KEY' environment variable or pass key to 'Brave(api_key="...")'.

error pydantic.error_wrappers.ValidationError: 1 validation error for WebSearchResult title none is not an allowed value (type=type_error.none.not_allowed) ↓

cause The Brave Search API sometimes returns responses that don't match the expected pydantic schema (e.g., missing title).

fix

Upgrade to >=0.1.8 and use 'raw=True' in the search call to bypass validation, or handle the error gracefully.

Warnings

gotcha The Python package name on PyPI is 'brave-search', but the import module is 'brave'. Doing 'import brave_search' will fail. ↓

fix Use 'pip install brave-search' and 'from brave import Brave'.

gotcha The API key must be set as an environment variable 'BRAVE_API_KEY' or passed directly to the Brave constructor. If not set, the library may raise an authentication error. ↓

fix Set 'BRAVE_API_KEY' environment variable or pass key to 'Brave(api_key="...")'.

deprecated The 'raw' parameter was added in v0.1.8 to bypass pydantic validation if it fails. In earlier versions, pydantic validation errors would block the response entirely. ↓

fix Upgrade to >=0.1.8 and pass 'raw=True' to the search method to get raw JSON if validation fails.

Imports

Brave
wrong
```
from brave_search import Brave
```
correct
```
from brave import Brave
```
The package name on PyPI is 'brave-search', but the import module is 'brave'.

Quickstart

Instantiate with your API key (set as env var BRAVE_API_KEY) and perform a simple web search.

from brave import Brave
import os

api_key = os.environ.get('BRAVE_API_KEY', '')
brave = Brave(api_key=api_key)

search_results = brave.search(q='Python programming', count=5)
for result in search_results.web_results:
    print(result.title, result.url)