How do I apply a custom site selection with Brave Goggles?

Definition: A Brave Goggle is a set of rules that changes the ordering or inclusion of results from Brave's search index. In the Web Search API, the goggles parameter accepts a hosted rules file URL or inline rules for selecting sites and matching URL patterns.

Key facts

• As of 17 October 2026, Brave's Web Search API reference accepts up to 3 Goggles per request and marks goggles_id as deprecated.
• Brave's Goggles documentation allows hosted URLs and inline definitions in the same request. Multiple rules within an inline definition are separated by newlines.
• Brave's syntax quickstart supports domain restrictions through site=, URL patterns and an explicit $discard action for removing matches.
• Brave's Getting Started guide explains that a generic $discard rule excludes results that match no instruction in the Goggle.

How does the request carry the rules?

The Web Search API reference defines goggles as a string or a list of strings. The following illustrative request uses an inline domain exclusion from Brave's social-network filtering example. The subscription token authenticates the request.

curl -G 'https://api.search.brave.com/res/v1/web/search' \
  --data-urlencode 'q=web development' \
  --data-urlencode 'goggles=$discard,site=facebook.com' \
  -H 'X-Subscription-Token: YOUR_API_KEY'

Brave's Goggles documentation specifies repeating the goggles query parameter for multiple Goggles. A single value can contain several rules: newline characters are encoded as %0A in the query string. Hosted files accommodate larger rule sets without putting every instruction in the URL.

Which filtering rules are supported?

The syntax quickstart defines one instruction per line. A plain pattern matches anywhere in a URL; site= restricts an instruction to a domain. These examples from that file target all pages of a site and then its blog path:

$site=brave.com
/blog/$site=brave.com

A rule without an explicit action raises matching results in the ordering. $downrank lowers their position, and $discard removes them. Patterns support * for zero or more characters, | at the beginning or end for prefix or suffix anchoring, and ^ for a URL delimiter or the end of the URL.

For selection limited to matching sites, the Getting Started guide specifies a generic $discard rule. Combining that default with the site syntax gives this illustrative selection:

$discard
$site=brave.com

The first line excludes unmatched results; the second retains matching Brave site results. Without the generic exclusion, other relevant results can remain. A targeted discard takes precedence over a rule that raises or lowers the same result.

How is a hosted Goggle made available?

Brave's Goggles documentation lists GitHub public repositories, GitHub Gists and GitLab public files or snippets as hosting options. The file includes name, description, public and author metadata, written as lines beginning with !.

The hosted URL is submitted at Brave's Goggle creation page before API use. The registered URL then becomes the value of goggles in the request.

Related terms

• Brave Search API
• How do I filter Brave Search API results by date?
• How do I retrieve additional source passages from Brave Search API?

FAQ

Can I combine a hosted file with inline rules?

Yes. Brave's Goggles documentation allows a mix of hosted URLs and inline definitions within the limit of 3 values per query.

How do I update a hosted Goggle?

You edit the hosted file and resubmit its URL at the creation page. Brave's Getting Started guide states that resubmission triggers a fresh fetch and makes the updated rules available in search.

Sources

1. Brave, "Web Search", undated
2. Brave, "Goggles", undated
3. Brave, "Quickstart", undated
4. Brave, "Getting Started", undated

---

Check how a page reads to answer engines. Open the GEO score analyzer