/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` | bool | No | - | Get up to 5 extra snippets per result | | `operators` | bool | No | `true` | Apply search operators | | `units` | string | No | - | Measurement units (`metric`/`imperial`) | | `enable_rich_callback` | bool | No | `false` | Enable rich 3rd party data callback | | `include_fetch_metadata` | bool | No | `false` | Include `fetched_content_timestamp` on results |

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