Skip to content
Back to top
View this page
Edit this page

# Brave Engines

Brave offers two different engines for SearXNG:

1. The standard engine (`brave`) uses the web interface.

2. The API engine (`braveapi`) uses the official REST API.

## Brave Standard Engine

Brave supports the categories listed in `brave_category` (General, news, videos, images). The support of `paging` and `time range` is limited (see remarks).

Configured `brave` engines:

    - name: brave
      engine: brave
      ...
      brave_category: search
      time_range_support: true
      paging: true

    - name: brave.images
      engine: brave
      ...
      brave_category: images

    - name: brave.videos
      engine: brave
      ...
      brave_category: videos

    - name: brave.news
      engine: brave
      ...
      brave_category: news

    - name: brave.goggles
      time_range_support: true
      paging: true
      ...
      brave_category: goggles

### Brave regions

Brave uses two-digit tags for the regions like `ca` while SearXNG deals with locales. To get a mapping, all officiat de-facto languages of the Brave region are mapped to regions in SearXNG (see `babel`):

    "regions": {
      ..
      "en-CA": "ca",
      "fr-CA": "ca",
      ..
     }

Note

The language (aka region) support of Brave’s index is limited to very basic languages. The search results for languages like Chinese or Arabic are of low quality.

### Brave Goggles

Goggles allow you to choose, alter, or extend the ranking of Brave Search results (Goggles Whitepaper). Goggles are openly developed by the community of Brave Search users.

Select from the list of Goggles people have published, or create your own (Goggles Quickstart).

### Brave languages

Brave’s language support is limited to the UI (menus, area local notations, etc). Brave’s index only seems to support a locale, but it does not seem to support any languages in its index. The choice of available languages is very small (and its not clear to me where the difference in UI is when switching from en-us to en-ca or en-gb).

In the `EngineTraits object` the UI languages are stored in a custom field named `ui_lang`:

    "custom": {
      "ui_lang": {
        "ca": "ca",
        "de-DE": "de-de",
        "en-CA": "en-ca",
        "en-GB": "en-gb",
        "en-US": "en-us",
        "es": "es",
        "fr-CA": "fr-ca",
        "fr-FR": "fr-fr",
        "ja-JP": "ja-jp",
        "pt-BR": "pt-br",
        "sq-AL": "sq-al"
      }
    },

### Implementations

searx.engines.brave.brave_category: Literal['search', 'videos', 'images', 'news', 'goggles'] = 'search'

  Brave supports common web-search, videos, images, news, and goggles search.

  - `search`: Common WEB search

  - `videos`: search for videos

  - `images`: search for images

  - `news`: search for news

  - `goggles`: Common WEB search with custom rules, requires a `Goggles` URL.

searx.engines.brave.Goggles: str = ''

  This should be a URL ending in `.goggle`

searx.engines.brave.brave_spellcheck = False

  Brave supports some kind of spell checking. When activated, Brave tries to fix typos, e.g. it searches for `food` when the user queries for `fooh`. In the UI of Brave the user gets warned about this, since we can not warn the user in SearXNG, the spellchecking is disabled by default.

searx.engines.brave.paging = False

  Brave only supports paging in `brave_category` `search` (UI category All) and in the goggles category.

searx.engines.brave.max_page = 10

  Tested 9 pages maximum (`&offset=8`), to be save max is set to 10. Trying to do more won’t return any result and you will most likely be flagged as a bot.

searx.engines.brave.time_range_support = False

  Brave only supports time-range in `brave_category` `search` (UI category All) and in the goggles category.

searx.engines.brave.fetch_traits(engine_traits: EngineTraits)

  Fetch languages and regions from Brave.

## Brave API Engine

Engine to search using the Brave (WEB) Search API.

### Configuration

The engine has the following mandatory setting:

- `api_key`

Optional settings are:

- `results_per_page`

    - name: braveapi
      engine: braveapi
      api_key: 'YOUR-API-KEY'  # required
      results_per_page: 20     # optional

The API supports paging and time filters.

searx.engines.braveapi.api_key: str = ''

  API key for Brave Search API (required).

searx.engines.braveapi.results_per_page: int = 20

  Maximum number of results per page (default 20).

searx.engines.braveapi.base_url = 'https://api.search.brave.com/res/v1/web/search'

  Base URL for the Brave Search API.

searx.engines.braveapi.time_range_map = {'day': 'past_day', 'month': 'past_month', 'week': 'past_week', 'year': 'past_year'}

  Mapping of SearXNG time ranges to Brave API time ranges.

searx.engines.braveapi.init(_)

  Initialize the engine.

searx.engines.braveapi.request(query: str, params: OnlineParams) → None

  Create the API request.

searx.engines.braveapi.response(resp: SXNG_Response) → EngineResults

  Process the API response and return results.

The API engine requires an API key from Brave. This can be obtained from the API Dashboard.