web-search

Web Search

Requires API Key: Get one at https://api.search.brave.com

Plan: Included in the Search plan. See https://api-dashboard.search.brave.com/app/subscriptions/subscribe

Quick Start (cURL)

Basic Search

curl -s "https://api.search.brave.com/res/v1/web/search?q=python+web+frameworks" \  -H "Accept: application/json" \  -H "X-Subscription-Token: ${BRAVE_SEARCH_API_KEY}"

With Parameters

curl -s "https://api.search.brave.com/res/v1/web/search" \  -H "Accept: application/json" \  -H "X-Subscription-Token: ${BRAVE_SEARCH_API_KEY}" \  -G \  --data-urlencode "q=rust programming tutorials" \  --data-urlencode "country=US" \  --data-urlencode "search_lang=en" \  --data-urlencode "count=10" \  --data-urlencode "safesearch=moderate" \  --data-urlencode "freshness=pm"

Endpoint

GET https://api.search.brave.com/res/v1/web/searchPOST https://api.search.brave.com/res/v1/web/search

Note: Both GET and POST methods are supported. POST is useful for long queries or complex Goggles.

Authentication: X-Subscription-Token: <API_KEY> header

Optional Headers:

• Accept-Encoding: gzip — Enable gzip compression

When to Use Web Search

Parameters

Freshness Values

Result Filter Values

Filter types: discussions, faq, infobox, news, query, videos, web, locations

# Only web and video resultscurl "...&result_filter=web,videos"

Location Headers (Optional)

For location-aware results, add these headers. Lat/Long is sufficient when coordinates are known — the other headers are only needed as a fallback when coordinates are unavailable.

Priority: X-Loc-Lat + X-Loc-Long take precedence. When provided, downstream services resolve the location directly from coordinates and the text-based headers (City, State, Country, Postal-Code) are not used for location resolution. Provide text-based headers only when you don't have coordinates. Sending both won't break anything — lat/long simply wins.

Response Format

Response Fields

JSON Example

{  "type": "search",  "query": {    "original": "python frameworks",    "altered": "python web frameworks",    "spellcheck_off": false,    "more_results_available": true  },  "web": {    "type": "search",    "results": [      {        "title": "Top Python Web Frameworks",        "url": "https://example.com/python-frameworks",        "description": "A comprehensive guide to Python web frameworks...",        "age": "2 days ago",        "language": "en",        "meta_url": {          "scheme": "https",          "netloc": "example.com",          "hostname": "example.com",          "path": "/python-frameworks"        },        "thumbnail": {          "src": "https://...",          "original": "https://original-image-url.com/img.jpg"        },        "extra_snippets": ["Additional excerpt 1...", "Additional excerpt 2..."]      }    ],    "family_friendly": true  },  "mixed": {    "type": "mixed",    "main": [      {"type": "web", "index": 0, "all": false},      {"type": "web", "index": 1, "all": false},      {"type": "videos", "all": true}    ],    "top": [],    "side": []  },  "videos": { "...": "..." },  "news": { "...": "..." },  "rich": {    "type": "rich",    "hint": {      "vertical": "weather",      "callback_key": "<callback_key_hex>"    }  }}

Mixed Response

The mixed object defines the preferred display order of results across types. It contains three arrays:

Each entry is a ResultReference with type (e.g., "web", "videos"), index (into the corresponding result array), and all (true to include all results of that type at this position).

Search Operators

Set operators=false to disable operator parsing.

Goggles (Custom Ranking) — Unique to Brave

Goggles let you re-rank search results — boost trusted sources, suppress SEO spam, or build focused search scopes.

Hosted goggles must be on GitHub/GitLab, include ! name:, ! description:, ! author: headers, and be registered at https://search.brave.com/goggles/create. Inline rules need no registration.

Syntax: $boost=N / $downrank=N (1–10), $discard, $site=example.com. Combine with commas: $site=example.com,boost=3. Separate rules with (%0A).

Allow list: $discard$site=docs.python.org$site=developer.mozilla.org — Block list: $discard,site=pinterest.com$discard,site=quora.com

Resources: Discover · Syntax · Quickstart

Rich Data Enrichments

For queries about weather, stocks, sports, currency, etc., use the rich callback workflow:

# 1. Search with rich callback enabledcurl -s "https://api.search.brave.com/res/v1/web/search?q=weather+san+francisco&enable_rich_callback=true" \  -H "X-Subscription-Token: ${BRAVE_SEARCH_API_KEY}"# Response includes: "rich": {"hint": {"callback_key": "abc123...", "vertical": "weather"}}# 2. Get rich data with the callback keycurl -s "https://api.search.brave.com/res/v1/web/rich?callback_key=abc123..." \  -H "X-Subscription-Token: ${BRAVE_SEARCH_API_KEY}"

Supported Rich Types: Calculator, Definitions, Unit Conversion, Unix Timestamp, Package Tracker, Stock, Currency, Cryptocurrency, Weather, American Football, Baseball, Basketball, Cricket, Football/Soccer, Ice Hockey, Web3, Translator

Rich Callback Endpoint

GET https://api.search.brave.com/res/v1/web/rich

Use Cases

• General-purpose search integration: Richest result set (web, news, videos, discussions, FAQ, infobox, locations) in one call. For RAG/LLM grounding, prefer llm-context.
• Structured data extraction: Products, recipes, ratings, articles via schemas and typed fields on results.
• Custom search with Goggles: Unique to Brave. Boost/discard sites with inline rules or hosted Goggles for fully customized ranking.

Notes

• Pagination: Use offset (0-9) with count to page through results
• Count: Max 20 for web search; actual results may be less than requested