web

View skill file Skill file for Search

Search the web from a large independent index of web pages.

Authorization

x-subscription-token string header required
The subscription token that was generated for the product.

Query Parameters

q string required
The user’s search query term. Query can not be empty. Maximum of 400 characters and 50 words in the query.
country enum<string>
The 2 character country code where the search results come from.
Default: "US"
Available options: ARAUAT
search_lang enum<string>
The 2 or more character language code for which the search results are provided.
Default: "en"
Available options: areubn
ui_lang enum<string>
User interface language preferred in response. Usually of the format <language_code>-<country_code>. For more, see RFC 9110.
Default: "en-US"
Available options: es-ARen-AUde-AT
count integer

The number of search results returned in response. The maximum is 20. The actual number delivered may be less than requested. Combine this parameter with offset to paginate search results.

NOTE: Count only applies to web results.

Min: 1 Max: 20 Default: 20
offset integer

The zero based offset that indicates number of search result pages (count) to skip before returning the result. The default is 0 and the maximum is 9. The actual number delivered may be less than requested.

Use this parameter along with the count parameter to page results. For example, if your user interface displays 10 search results per page, set count to 10 and offset to 0 to get the first page of results. For each subsequent page, increment offset by 1 (for example, 0, 1, 2). It is possible for multiple pages to include some overlap in results.

Min: 0 Max: 9 Default: 0
safesearch enum<string>

Filters search results for adult content. The following values are supported:

  • off - No filtering is done.
  • moderate - Filters explicit content, like images and videos, but allows adult domains in the search results.
  • strict - Drops all adult content from search results.
Default: "moderate"
Available options: offmoderatestrict
spellcheck boolean
Whether to spell check provided query. If the spell checker is enabled, the modified query is always used for search. The modified query can be found in altered key from the query response model.
Default: true
freshness string
  • pm
  • 2022-04-01to2022-07-30

Filters search results by page age. The age of a page is determined by the most relevant date reported by the content, such as its published or last modified date. The following values are supported:

  • pd - Pages aged 24 hours or less.
  • pw - Pages aged 7 days or less.
  • pm - Pages aged 31 days or less.
  • py - Pages aged 365 days or less.
  • YYYY-MM-DDtoYYYY-MM-DD - A custom date range is also supported by specifying start and end dates e.g. 2022-04-01to2022-07-30.
Default: ""
text_decorations boolean
Whether display strings (e.g. result snippets) should include decoration markers (e.g. highlighting characters).
Default: true
result_filter string[]
  • web
  • videos
  • web,videos

A comma delimited string of result types to include in the search response. Not specifying this parameter will return back all result types in search response where data is available and a plan with the corresponding option is subscribed. The response always includes query and type to identify any query modifications and response type respectively. Available result filter values are: discussions, faq, infobox, news, query, summarizer, videos, web, locations.

NOTE: count param only applies to web results.

units enum<string>

The measurement units. The following values are supported:

  • metric - The standardized measurement system (km, celcius…)
  • imperial - The British Imperial system of units (mile, fahrenheit…)
Available options: imperialmetric
goggles_id string deprecated
  • https://raw.githubusercontent.com/brave/goggles-quickstart/main/goggles/hacker_news.goggle Prioritizes domains popular with the Hacker News
Goggles act as a custom re-ranking on top of Brave’s search index. For more details, refer to the Goggles repository. This parameter is deprecated. Please use the goggles parameter.
goggles string | string[]
  • https://raw.githubusercontent.com/brave/goggles-quickstart/main/goggles/hacker_news.goggle Prioritizes domains popular with the Hacker News
  • ! name: Social Networks ! description: Removes social networks ! public: true ! author: Average Joe ! avatar: #de0320 $discard,site=facebook.com $discard,site=x.com $discard,site=instagram.com Social media blocker
Goggles act as a custom re-ranking on top of Brave’s search index. The parameter supports both a url where the Goggle is hosted or the definition of the goggle. For more details, see the Goggles documentation. The parameter can be repeated to query with multiple goggles.
extra_snippets boolean
A snippet is an excerpt from a page you get as a result of the query, and extra_snippets allow you to get up to 5 additional, alternative excerpts.
summary boolean
This parameter enables summary key generation in web search results. This is required for summarizer to be enabled.
enable_rich_callback boolean

Enable rich callback. Allows you to get real time rich results via a callback URL when they are relevant to your query.

NOTE: Requires Search subscription.

Default: false
include_fetch_metadata boolean
Include fetch metadata.
Default: false
operators boolean
Whether to apply search operators
Default: true

Headers

x-loc-lat number
  • 37.787
The latitude of the client’s geographical location in degrees, to provide relevant local results. The latitude must be greater than or equal to -90.0 degrees and less than or equal to +90.0 degrees.
x-loc-long number
  • -122.4
The longitude of the client’s geographical location in degrees, to provide relevant local results. The longitude must be greater than or equal to -180.0 and less than or equal to +180.0 degrees.
x-loc-timezone string
  • America/San_Francisco IANA timezone for San Francisco in USA
The IANA timezone for the client’s device. For complete list of IANA timezones and location mappings see IANA Database and Geonames Database.
x-loc-city string
  • San Francisco City in USA
The generic name of the client city.
x-loc-state string
  • CA
A code which could be up to three characters, that represent the client’s state/region. The region is the first-level subdivision (the broadest or least specific) of the ISO 3166-2 code.
x-loc-state-name string
  • California
The name of the client’s state/region. The region is the first-level subdivision (the broadest or least specific) of the ISO 3166-2 code.
x-loc-country enum<string>

The two letter country code for the client’s country. For a list of country codes, see ISO 3166-1 alpha-2.

Available options: ADAEAF
x-loc-postal-code string
  • 94105 Postal code in San Francisco, California, US
The client’s postal code.
api-version string
The API version to use. This is denoted by the format YYYY-MM-DD. Default is the latest that is available. Read more about API versioning.
accept enum<string>
The default supported media type is application/json.
Default: "application/json"
Available options: application/json*/*
cache-control "no-cache"
Brave Search will return cached content by default. To prevent caching set the Cache-Control header to no-cache. This is currently done as best effort.
user-agent string
  • Mozilla/5.0 (Linux; Android 12) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/103.0.5060.71 Mobile Safari/537.36 Android
  • Mozilla/5.0 (iPhone; CPU iPhone OS 15_5 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) CriOS/103.0.5060.63 Mobile/15E148 Safari/604.1 iOS
  • Mozilla/5.0 (Macintosh; Intel Mac OS X 12_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/103.0.0.0 Safari/537.36 macOS
  • Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/103.0.0.0 Safari/537.36 Windows
The user agent originating the request. Brave search can utilize the user agent to provide a different experience depending on the device as described by the string. The user agent should follow the commonly used browser agent strings on each platform. For more information on curating user agents, see RFC 9110.

Responses

200 Successful Response
type "search"
query object nullable
discussions object nullable
A model representing a discussion cluster relevant to the query.
faq object nullable
Frequently asked questions relevant to the search query term.
infobox object nullable
Aggregated information on an entity shown as an infobox.
locations object nullable
A model representing location results.
mixed object nullable
The ranking order of results on a search result page.
news object nullable
videos object nullable
web object nullable
A model representing a collection of web search results.
summarizer object nullable
rich object nullable
404 Not Found
type string
error object required
time integer
422 Unprocessable Entity
type string
error object required
time integer
429 Too Many Requests
type string
error object required
time integer