web-search

name	web-search
description	USE FOR web search. Returns ranked results with snippets, URLs, thumbnails. Supports freshness filters, SafeSearch, Goggles for custom ranking, pagination. Primary search endpoint.

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/search
POST 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

Feature	Web Search (this)	LLM Context (llm-context)	Answers (answers)
Output	Structured results (links, snippets, metadata)	Pre-extracted page content for LLMs	End-to-end AI answers with citations
Result types	Web, news, videos, discussions, FAQ, infobox, locations, rich	Extracted text chunks, tables, code	Synthesized answer + source list
Unique features	Goggles, structured data (schemas), rich callbacks	Token budget control, threshold modes	Multi-iteration search, streaming, OpenAI SDK compatible
Speed	Fast (~0.5-1s)	Fast (<1s)	Slower (~30-180s)
Best for	Search UIs, data extraction, custom ranking	RAG pipelines, AI agents, grounding	Chat interfaces, thorough research

Parameters

Parameter	Type	Required	Default	Description
q	string	Yes	-	Search query (1-400 chars, max 50 words)
country	string	No	US	Search country (2-letter country code or ALL)
search_lang	string	No	en	Language preference (2+ char language code)
ui_lang	string	No	en-US	UI language (e.g., "en-US")
count	int	No	20	Max results per page (1-20)
offset	int	No	0	Page offset for pagination (0-9)
safesearch	string	No	moderate	Adult content filter (off/moderate/strict)
freshness	string	No	-	Time filter (pd/pw/pm/py or date range)
text_decorations	bool	No	true	Include highlight markers
spellcheck	bool	No	true	Auto-correct query
result_filter	string	No	-	Filter result types (comma-separated)
goggles	string	No	-	Custom ranking filter (URL or inline)
extra_snippets

Freshness Values

Value	Description
pd	Past day (24 hours)
pw	Past week (7 days)
pm	Past month (31 days)
py	Past year (365 days)
YYYY-MM-DDtoYYYY-MM-DD	Custom date range

Result Filter Values

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

# Only web and video results
curl "...&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.

Header	Type	Description
X-Loc-Lat	float	User latitude (-90.0 to 90.0)
X-Loc-Long	float	User longitude (-180.0 to 180.0)
X-Loc-Timezone	string	IANA timezone (e.g., "America/San_Francisco")
X-Loc-City	string	City name
X-Loc-State	string	State/region code (ISO 3166-2)
X-Loc-State-Name	string	State/region full name (e.g., "California")
X-Loc-Country	string	2-letter country code
X-Loc-Postal-Code	string	Postal code (e.g., "94105")

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

Field	Type	Description
type	string	Always "search"
query.original	string	The original search query
query.altered	string?	Spellcheck-corrected query (if changed)
query.cleaned	string?	Cleaned/normalized query
query.spellcheck_off	bool?	Whether spellcheck was disabled
query.more_results_available	bool	Whether more pages exist
query.show_strict_warning	bool?	True if strict safesearch blocked adult results
query.search_operators	object?	Applied search operators (applied, cleaned_query, sites)
web.type	string	Always "search"
web.results[].title	string	Page title
web.results[].url	string	Page URL
web.results[].description	string?	Snippet/description text
web.results[].age	string?	Human-readable age (e.g., "2 days ago")
web.results[].language	string?	Content language code
web.results[].meta_url	object	URL components (scheme, netloc, hostname, path)
web.results[].thumbnail	object?	Thumbnail (src, original)
web.results[].thumbnail.original

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": 
         
           
           
           
           
        
         
           
           
        
          
      
    
     
  
   
     
     
           
           
         
    
     
     
  
      
      
   
     
     
       
       
    
  

Mixed Response

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

Array	Purpose
main	Primary result list (ordered sequence of results to display)
top	Results to display above main results
side	Results to display alongside main results (e.g., infobox)

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

Operator	Syntax	Description
Site	site:example.com	Limit results to a specific domain
File extension	ext:pdf	Results with a specific file extension
File type	filetype:pdf	Results created in a specific file type
In title	intitle:python	Pages with term in the title
In body	inbody:tutorial	Pages with term in the body
In page	inpage:guide	Pages with term in title or body
Language	lang:es	Pages in a specific language (ISO 639-1)
Location	loc:us	Pages from a specific country (ISO 3166-1 alpha-2)
Include	+term	Force inclusion of a term
Exclude	-term	Exclude pages containing the term
Exact match	"exact phrase"	Match the exact phrase in order
AND	term1 AND term2	Both terms required (uppercase)
OR / NOT	term1 OR term2, NOT term	Logical operators (uppercase)

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.

Method	Example
Hosted	--data-urlencode "goggles=https://raw.githubusercontent.com/brave/goggles-quickstart/main/goggles/rust_programming.goggle"
Inline	--data-urlencode 'goggles=$discard\n$site=example.com'

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: Rules start with $ + comma-separated options. Actions (pick one): discard, boost[=N], downrank[=N] — N is an integer 1–10. Site filter: site=DOMAIN. Example: $site=example.com,boost=3. Separate rules with \n (%0A).

Allow list: $discard\n$site=docs.python.org\n$site=developer.mozilla.org — Block list: $discard,site=pinterest.com\n$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 enabled
curl -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 key
curl -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

Parameter	Type	Required	Description
callback_key	string	Yes	Callback key from the web search rich.hint.callback_key field

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