Overview

Goggles are a powerful feature that allows you to customize how search results are ranked. Using a simple domain-specific language, you can create instructions to boost, downrank, or completely filter results based on URL patterns, domains, and other criteria. This enables you to build personalized search experiences tailored to specific use cases or audiences.

Goggles work with both Web Search and News Search APIs, giving you fine-grained control over result ranking across different content types.

Key Features

Use Cases

Goggles are perfect for:

• Specialized Search Engines: Create vertical search experiences (e.g., tech blogs, academic sources only)
• Content Curation: Boost trusted sources and demote undesired content
• Brand Monitoring: Focus on specific news outlets or exclude competitors
• Research Applications: Filter scholarly sources or specific geographic regions
• Community Tools: Build search experiences tailored to specific communities or interests

Using Goggles with the API

Both Web Search and News Search APIs accept the goggles query parameter. You can provide Goggles in three ways:

• Hosted Goggles URL: A link to a Goggles file hosted on GitHub, GitLab, or Gist
• Inline Specification: Include Goggles rules directly in the request
• Mixed: Combine multiple hosted Goggles and inline rules by passing multiple URLs and inline rules

Using a Hosted Goggles

Hosted Goggles are ideal for complex rule sets as they avoid URL length limitations. Simply pass the URL of your hosted Goggles file:

curl "https://api.search.brave.com/res/v1/web/search" \
  --url-query "q=programming tutorials" \
  --url-query "goggles=https://raw.githubusercontent.com/brave/goggles-quickstart/main/goggles/tech_blogs.goggle" \
  -H "X-Subscription-Token: YOUR_API_KEY"

import requests

url = "https://api.search.brave.com/res/v1/web/search"
headers = {
    "Accept": "application/json",
    "Accept-Encoding": "gzip",
    "X-Subscription-Token": "YOUR_API_KEY"
}
params = {
    "q": "programming tutorials",
    "goggles": "https://raw.githubusercontent.com/brave/goggles-quickstart/main/goggles/tech_blogs.goggle"
}

response = requests.get(url, headers=headers, params=params)
results = response.json()

const url = new URL("https://api.search.brave.com/res/v1/web/search");
url.searchParams.append("q", "programming tutorials");
url.searchParams.append(
  "goggles",
  "https://raw.githubusercontent.com/brave/goggles-quickstart/main/goggles/tech_blogs.goggle"
);

const response = await fetch(url, {
  headers: {
    Accept: "application/json",
    "Accept-Encoding": "gzip",
    "X-Subscription-Token": "YOUR_API_KEY",
  },
});
const results = await response.json();
console.log(results);

Using Multiple Goggles

You can combine multiple hosted Goggles by passing multiple goggles parameters:

curl "https://api.search.brave.com/res/v1/web/search?q=rust+programming&goggles=https%3A%2F%2Fexample.com%2Fgoggle1.goggle&goggles=https%3A%2F%2Fexample.com%2Fgoggle2.goggle" \
  -H "X-Subscription-Token: YOUR_API_KEY"

import requests

url = "https://api.search.brave.com/res/v1/web/search"
headers = {
    "Accept": "application/json",
    "Accept-Encoding": "gzip",
    "X-Subscription-Token": "YOUR_API_KEY"
}

# Pass multiple goggles as a list
params = [
    ("q", "rust programming"),
    ("goggles", "https://example.com/goggle1.goggle"),
    ("goggles", "https://example.com/goggle2.goggle")
]

response = requests.get(url, headers=headers, params=params)
results = response.json()

const url = new URL("https://api.search.brave.com/res/v1/web/search");
url.searchParams.append("q", "rust programming");

// Append multiple goggles parameters
url.searchParams.append("goggles", "https://example.com/goggle1.goggle");
url.searchParams.append("goggles", "https://example.com/goggle2.goggle");

const response = await fetch(url, {
  headers: {
    Accept: "application/json",
    "Accept-Encoding": "gzip",
    "X-Subscription-Token": "YOUR_API_KEY",
  },
});
const results = await response.json();
console.log(results);

Using Inline Goggles Specifications

For simple use cases, you can pass Goggles rules directly in the query parameter. This is useful for quick experiments or simple filtering rules:

curl "https://api.search.brave.com/res/v1/web/search?q=rust+programming&goggles=https%3A%2F%2Fexample.com%2Fgoggle1.goggle&goggles=https%3A%2F%2Fexample.com%2Fgoggle2.goggle" \
  -H "X-Subscription-Token: YOUR_API_KEY"

import requests
from urllib.parse import quote

url = "https://api.search.brave.com/res/v1/web/search"
headers = {
    "Accept": "application/json",
    "Accept-Encoding": "gzip",
    "X-Subscription-Token": "YOUR_API_KEY"
}

# Inline Goggles to boost dev.to results
goggle_rules = "$boost=3,site=dev.to"

params = {
    "q": "web development",
    "goggles": goggle_rules
}

response = requests.get(url, headers=headers, params=params)
results = response.json()

const url = new URL("https://api.search.brave.com/res/v1/web/search");
url.searchParams.append("q", "web development");

// Inline Goggles to boost dev.to results
const gogglesRules = "$boost=3,site=dev.to";
url.searchParams.append("goggles", gogglesRules);

const response = await fetch(url, {
  headers: {
    Accept: "application/json",
    "Accept-Encoding": "gzip",
    "X-Subscription-Token": "YOUR_API_KEY",
  },
});
const results = await response.json();
console.log(results);

Delimit the rules with \n (encoded to %0A) to include multiple inline rules in one goggles parameter.

Using Goggles with News Search

Goggles work the same way with the News Search API. This allows you to customize news result rankings based on your preferred sources:

curl "https://api.search.brave.com/res/v1/news/search?q=technology&goggles=https%3A%2F%2Fexample.com%2Fmy-news-sources.goggle" \
  -H "X-Subscription-Token: YOUR_API_KEY"

Goggles Syntax Overview

Goggles use a simple domain-specific language (DSL) to express ranking instructions. Each instruction targets URLs and specifies how matching results should be treated.

Basic Actions

URL Targeting

Example Goggles File

! name: Tech Blogs
! description: Boost results from popular tech blogs
! public: true
! author: Your Name

! Boost popular tech blogs
$boost=3,site=dev.to
$boost=3,site=medium.com
$boost=3,site=hashnode.dev
$boost=2,site=css-tricks.com

! Downrank content farms
$downrank=5,site=w3schools.com

! Discard specific domains entirely
$discard,site=spam-example.com

Conflict Resolution

When multiple instructions match the same URL, Goggles follow this precedence:

1. $discard takes highest priority (unless generic)
2. $boost takes precedence over $downrank
3. Higher strength values take precedence over lower ones

For example, if one rule says $downrank=3,site=example.com and another says $boost=2,site=example.com, the boost rule wins.

Creating and Hosting Goggles

To use a hosted Goggles with the API, you need to:

1. Create a Goggles file — Write your rules in a plain text file (.goggle extension recommended)
2. Add metadata — Include required metadata at the top of your file
3. Host the file — Upload to one of the supported platforms:
   • GitHub Gist (public or secret)
   • GitHub (public repositories)
   • GitLab (public files or snippets)
4. Submit for validation — Register your Goggles at search.brave.com/goggles/create

Required Metadata

Every Goggles file must include these metadata fields at the top:

! name: My Custom Goggles
! description: Brief description of what this Goggles does
! public: false
! author: Your Name

Optional Metadata

Optional metadata can be added to your Goggles file to provide additional information about the Goggles.

! homepage: https://example.com
! issues: https://github.com/user/repo/issues
! avatar: #FF5733
! license: MIT

Limitations

Keep these limitations in mind when creating Goggles:

• File size: Maximum 2MB per Goggles file
• Instruction count: Maximum 100,000 instructions per file
• Instruction length: Maximum 500 characters per instruction
• Wildcards: Maximum 2 * characters per instruction
• Carets: Maximum 2 ^ characters per instruction

Best Practices

Example Goggles

Brave provides several example Goggles for learning purposes:

Browse more community-created Goggles on the Goggles Discovery page.

Related Resources