Web Search

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

View skill file Skill file for Search

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 600 characters and 75 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 the plan has the corresponding option activated. 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 a single Goggle or a list of up to 3 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 plan.

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.
Min: -90 Max: 90
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.
Min: -180 Max: 180
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"
Default: "search"
query object nullable
Search query string and its modifications that are used for search.
query.original string required
The original query that was requested.
query.show_strict_warning boolean nullable
Whether to show a warning that strict safesearch filtered results.
query.altered string nullable
The altered query by the spellchecker.
query.cleaned string nullable
The cleaned normalized query.
query.safesearch boolean nullable
Whether safesearch is active.
query.is_navigational boolean nullable
Whether the query is navigational (user wants to go to a specific site).
query.is_geolocal boolean nullable
Whether the query has local intent.
query.local_decision string nullable
The local search decision for the query.
query.local_locations_idx integer nullable
Index of the local location result.
query.is_news_breaking boolean nullable
Whether the query is related to breaking news.
query.ask_for_location boolean nullable
Whether to prompt the user for their location.
query.language object nullable
The detected language of the query.
query.language.main string required
The main language seen in the string.
query.spellcheck_off boolean nullable
Whether spellcheck is disabled for this query.
query.country string nullable
The country code for the query.
query.bad_results boolean nullable
Whether the results are considered low quality.
query.should_fallback boolean nullable
Whether to fallback to alternative ranking.
query.lat string nullable
The latitude for location-based queries.
query.long string nullable
The longitude for location-based queries.
query.postal_code string nullable
The postal code for location-based queries.
query.city string nullable
The city for location-based queries.
query.header_country string nullable
The country from request headers.
query.more_results_available boolean nullable
Whether more results are available for pagination.
query.state string nullable
The state/region for location-based queries.
query.custom_location_label string nullable
A custom label for the location.
query.reddit_cluster string nullable
Reddit cluster identifier for discussion results.
query.summary_key string nullable
Key to retrieve AI-generated summary for the query.
query.search_operators object nullable
Search operators that were detected and applied to the query.
query.search_operators.applied boolean
Whether search operators were applied to the query.
Default: false
query.search_operators.cleaned_query string nullable
The query after search operators have been processed.
query.search_operators.sites string[] nullable
List of site domains extracted from site: operators.
query.related_queries string[]
Related queries for the query.
Default: []
discussions object nullable
Discussions clusters aggregated from forum posts that are relevant to the query.
discussions.type "search"
The type identifying a discussion cluster. Currently the value is always search.
Default: "search"
discussions.results object[] required
A list of discussion results.
discussions.results.title string required
The title of the web page.
discussions.results.url string required
The URL where the page is served.
discussions.results.is_source_local boolean
Whether the result is from a local source.
Default: false
discussions.results.is_source_both boolean
Whether the result is from both local and global sources.
Default: false
discussions.results.description string nullable
A description for the web page.
Default: ""
discussions.results.page_age string nullable
The page’s date, based on its published or last modified date.
discussions.results.page_fetched string nullable
A date representing when the web page was last fetched.
discussions.results.fetched_content_timestamp integer nullable
The timestamp when the content was fetched.
discussions.results.profile object nullable
A profile associated with the web page.
discussions.results.language string
The main language on the web search result.
Default: "en"
discussions.results.family_friendly boolean
Whether the web page is family friendly.
Default: true
discussions.results.type "discussion"
The discussion result type identifier. The value is always discussion.
Default: "discussion"
discussions.results.subtype string
A sub type identifying the web search result type.
Default: "generic"
discussions.results.is_live boolean
Whether the web search result is currently live. Default value is false.
Default: false
discussions.results.deep_results object nullable
Gathered information on a web search result.
discussions.results.schemas any[] nullable
A list of schemas (structured data) extracted from the page. The schemas try to follow schema.org and will return anything we can extract from the HTML that can fit into these models.
discussions.results.meta_url object nullable
Aggregated information on the URL associated with the web search result.
discussions.results.thumbnail object nullable
The thumbnail of the web search result.
discussions.results.age string nullable
A human-readable representation of the web search result’s age. For example, 2 days ago.
discussions.results.location object nullable
The location details if the query relates to a restaurant.
discussions.results.restaurant object nullable
Deprecated. Use location instead.
discussions.results.video object nullable
The video associated with the web search result.
discussions.results.movie object nullable
The movie associated with the web search result.
discussions.results.faq object nullable
Any frequently asked questions associated with the web search result.
discussions.results.qa object nullable
Any question answer information associated with the web search result page.
discussions.results.book object nullable
Any book information associated with the web search result page.
discussions.results.rating object nullable
Rating found for the web search result page.
discussions.results.article object nullable
An article found for the web search result page.
discussions.results.product object | object nullable
The main product and a review that is found on the web search result page.
discussions.results.product_cluster object | object[] nullable
A list of products and reviews that are found on the web search result page.
discussions.results.cluster_type string nullable
A type representing a cluster. The value can be product_cluster.
discussions.results.cluster object[] nullable
A list of web search results.
discussions.results.creative_work object nullable
Aggregated information on the creative work found on the web search result.
discussions.results.music_recording object nullable
Aggregated information on music recording found on the web search result.
discussions.results.review object nullable
Aggregated information on the review found on the web search result.
discussions.results.recipe object nullable
Aggregated information on a recipe found on the web search result page.
discussions.results.software object nullable
Aggregated information on a software product found on the web search result page.
discussions.results.organization object nullable
Aggregated information on a organization found on the web search result page.
discussions.results.content_type string nullable
The content type associated with the search result page.
discussions.results.extra_snippets string[] nullable
A list of extra alternate snippets for the web search result.
discussions.results.icons object[] nullable
Icons associated with the search result.
discussions.results.data object nullable
The enriched aggregated data for the relevant forum post.
discussions.mutated_by_goggles boolean
Whether the discussion results are changed by Goggles. The value is false by default.
Default: false
faq object nullable
Frequently asked questions that are relevant to the search query.
faq.type "faq"
The FAQ result type identifier. The value is always faq.
Default: "faq"
faq.results object[] required
A list of aggregated question answer results relevant to the query.
faq.results.question string required
The question being asked.
faq.results.answer string required
The answer to the question.
faq.results.title string required
The title of the post.
faq.results.url string required
The URL pointing to the post.
faq.results.meta_url object nullable
Aggregated information about the URL.
infobox object nullable
Aggregated information on an entity showable as an infobox.
infobox.type "graph"
The type identifier for infoboxes. The value is always graph.
Default: "graph"
infobox.results object | object | object | object | object[] required
A list of infoboxes associated with the query.
locations object nullable
Places of interest (POIs) relevant to location sensitive queries.
locations.type "locations"
Location type identifier. The value is always locations.
Default: "locations"
locations.results object[] required
An aggregated list of location sensitive results.
locations.results.title string required
The title of the web page.
locations.results.url string required
The URL where the page is served.
locations.results.is_source_local boolean
Whether the result is from a local source.
Default: false
locations.results.is_source_both boolean
Whether the result is from both local and global sources.
Default: false
locations.results.description string nullable
A description for the web page.
Default: ""
locations.results.page_age string nullable
The page’s date, based on its published or last modified date.
locations.results.page_fetched string nullable
A date representing when the web page was last fetched.
locations.results.fetched_content_timestamp integer nullable
The timestamp when the content was fetched.
locations.results.profile object nullable
A profile associated with the web page.
locations.results.language string nullable
A language classification for the web page.
locations.results.family_friendly boolean
Whether the web page is family friendly.
Default: true
locations.results.type "location_result"
Location result type identifier. The value is always location_result.
Default: "location_result"
locations.results.provider_url string required
The complete URL of the provider.
locations.results.coordinates any[] nullable
A list of coordinates associated with the location. This is a lat long represented as a floating point.
locations.results.zoom_level integer
The zoom level on the map.
Default: 7
locations.results.thumbnail object nullable
The thumbnail associated with the location.
locations.results.postal_address object nullable
The postal address associated with the location.
locations.results.opening_hours object nullable
The opening hours, if it is a business, associated with the location.
locations.results.contact object nullable
The contact of the business associated with the location.
locations.results.price_range string nullable
A display string used to show the price classification for the business.
locations.results.rating object nullable
The ratings of the business.
locations.results.distance object nullable
The distance of the location from the client.
locations.results.profiles object[] nullable
Profiles associated with the business.
locations.results.reviews object nullable
Aggregated reviews from various sources relevant to the business.
locations.results.pictures object nullable
A bunch of pictures associated with the business.
locations.results.action object nullable
An action to be taken.
locations.results.serves_cuisine string[] nullable
A list of cuisine categories served.
locations.results.categories string[]
A list of categories.
Default: []
locations.results.icon_category string nullable
An icon category.
locations.results.timezone string nullable
IANA timezone identifier.
locations.results.timezone_offset integer nullable
The UTC offset of the timezone.
locations.results.id string nullable
A temporary id associated with this result, which can be used to retrieve extra information about the location. It remains valid for 8 hours.
locations.results.results object[] nullable
Web results related to this location.
locations.provider object nullable
The provider of the location data.
mixed object nullable
Preferred ranked order of search results.
mixed.type "mixed"
The type representing the model mixed. The value is always mixed.
Default: "mixed"
mixed.main object[] nullable
The ranking order for the main section of the search result page.
mixed.main.type string required
The type of the result.
mixed.main.index integer nullable
The 0th based index where the result should be placed.
mixed.main.all boolean
Whether to put all the results from the type at specific position.
Default: false
mixed.top object[] nullable
The ranking order for the top section of the search result page.
mixed.top.type string required
The type of the result.
mixed.top.index integer nullable
The 0th based index where the result should be placed.
mixed.top.all boolean
Whether to put all the results from the type at specific position.
Default: false
mixed.side object[] nullable
The ranking order for the side section of the search result page.
mixed.side.type string required
The type of the result.
mixed.side.index integer nullable
The 0th based index where the result should be placed.
mixed.side.all boolean
Whether to put all the results from the type at specific position.
Default: false
news object nullable
News results relevant to the query.
news.type "news"
The type of API result. The value is always news.
Default: "news"
news.results object[] required
The list of news results.
news.results.title string required
The title of the web page.
news.results.url string required
The URL where the page is served.
news.results.is_source_local boolean
Whether the result is from a local source.
Default: false
news.results.is_source_both boolean
Whether the result is from both local and global sources.
Default: false
news.results.description string nullable
A description for the web page.
Default: ""
news.results.page_age string nullable
The page’s date, based on its published or last modified date.
news.results.page_fetched string nullable
A date representing when the web page was last fetched.
news.results.fetched_content_timestamp integer nullable
The timestamp when the content was fetched.
news.results.profile object nullable
A profile associated with the web page.
news.results.language string nullable
A language classification for the web page.
news.results.family_friendly boolean
Whether the web page is family friendly.
Default: true
news.results.meta_url object nullable
The aggregated information on the URL representing a news result.
news.results.source string nullable
The source of the news.
news.results.breaking boolean
Whether the news result is currently a breaking news.
Default: false
news.results.is_live boolean
Whether the news result is currently live.
Default: false
news.results.thumbnail object nullable
The thumbnail associated with the news result.
news.results.age string nullable
A human-readable representation of the news article’s age. For example, 2 days ago.
news.results.extra_snippets string[] nullable
A list of extra alternate snippets for the news search result.
news.results.icons object[] nullable
Icons associated with the news result.
news.mutated_by_goggles boolean
Whether the results are mutated by a goggle.
Default: false
videos object nullable
Videos results relevant to the query.
videos.type "videos"
The type of API result. The value is always videos.
Default: "videos"
videos.results object[] required
The list of video results.
videos.results.type "video_result"
The type of video search API result. The value is always video_result.
Default: "video_result"
videos.results.url string required
The source URL of the video.
videos.results.title string required
The title of the video.
videos.results.description string nullable
The description for the video.
videos.results.age string nullable
A human-readable representation of the video’s age. For example, 2 days ago.
videos.results.page_age string nullable
The page’s date, based on its published or last modified date.
videos.results.page_fetched string nullable
The ISO date time when the page was last fetched. The format is YYYY-MM-DDTHH:MM:SSZ.
videos.results.fetched_content_timestamp integer nullable
The timestamp when the content was fetched.
videos.results.video object nullable
Metadata for the video.
videos.results.meta_url object nullable
Aggregated information on the URL associated with the video search result.
videos.results.thumbnail object nullable
The thumbnail for the video.
videos.mutated_by_goggles boolean
Whether the results are mutated by a goggle.
Default: false
web object nullable
Web results relevant to the query.
web.type "search"
A type identifying web search results. The value is always search.
Default: "search"
web.results object[] required
A list of search results.
web.results.title string required
The title of the web page.
web.results.url string required
The URL where the page is served.
web.results.is_source_local boolean
Whether the result is from a local source.
Default: false
web.results.is_source_both boolean
Whether the result is from both local and global sources.
Default: false
web.results.description string nullable
A description for the web page.
Default: ""
web.results.page_age string nullable
The page’s date, based on its published or last modified date.
web.results.page_fetched string nullable
A date representing when the web page was last fetched.
web.results.fetched_content_timestamp integer nullable
The timestamp when the content was fetched.
web.results.profile object nullable
A profile associated with the web page.
web.results.language string
The main language on the web search result.
Default: "en"
web.results.family_friendly boolean
Whether the web page is family friendly.
Default: true
web.results.type "search_result"
A type identifying a web search result. The value is always search_result.
Default: "search_result"
web.results.subtype string
A sub type identifying the web search result type.
Default: "generic"
web.results.is_live boolean
Whether the web search result is currently live. Default value is false.
Default: false
web.results.deep_results object nullable
Gathered information on a web search result.
web.results.schemas any[] nullable
A list of schemas (structured data) extracted from the page. The schemas try to follow schema.org and will return anything we can extract from the HTML that can fit into these models.
web.results.meta_url object nullable
Aggregated information on the URL associated with the web search result.
web.results.thumbnail object nullable
The thumbnail of the web search result.
web.results.age string nullable
A human-readable representation of the web search result’s age. For example, 2 days ago.
web.results.location object nullable
The location details if the query relates to a restaurant.
web.results.restaurant object nullable
Deprecated. Use location instead.
web.results.video object nullable
The video associated with the web search result.
web.results.movie object nullable
The movie associated with the web search result.
web.results.faq object nullable
Any frequently asked questions associated with the web search result.
web.results.qa object nullable
Any question answer information associated with the web search result page.
web.results.book object nullable
Any book information associated with the web search result page.
web.results.rating object nullable
Rating found for the web search result page.
web.results.article object nullable
An article found for the web search result page.
web.results.product object | object nullable
The main product and a review that is found on the web search result page.
web.results.product_cluster object | object[] nullable
A list of products and reviews that are found on the web search result page.
web.results.cluster_type string nullable
A type representing a cluster. The value can be product_cluster.
web.results.cluster object[] nullable
A list of web search results.
web.results.creative_work object nullable
Aggregated information on the creative work found on the web search result.
web.results.music_recording object nullable
Aggregated information on music recording found on the web search result.
web.results.review object nullable
Aggregated information on the review found on the web search result.
web.results.recipe object nullable
Aggregated information on a recipe found on the web search result page.
web.results.software object nullable
Aggregated information on a software product found on the web search result page.
web.results.organization object nullable
Aggregated information on a organization found on the web search result page.
web.results.content_type string nullable
The content type associated with the search result page.
web.results.extra_snippets string[] nullable
A list of extra alternate snippets for the web search result.
web.results.icons object[] nullable
Icons associated with the search result.
web.family_friendly boolean
Whether the results are family friendly.
Default: true
summarizer object nullable
Summary key to get summary results for the query.
summarizer.type "summarizer"
The type of result. The value is always summarizer.
Default: "summarizer"
summarizer.key string required
The key to retrieve the full summary results.
rich object nullable
Callback information to retrieve rich results.
rich.type "rich"
Default: "rich"
rich.hint object nullable
rich.hint.vertical enum<string> required
The vertical associated with the callback. For the full list of verticals supported see the Rich Vertical list.
Available options: calculatorcryptocurrencycurrency
rich.hint.callback_key string required
The unique key for the callback.
404 Not Found
type string
Default: "ErrorResponse"
error object required
error.id string required
A unique identifier for this particular occurrence of the problem.
error.status integer required
The HTTP status code applicable to this problem, expressed as a string value.
error.detail string nullable
Explanation specific to this occurrence of the problem. Like title, this field’s value can be localized.
error.meta object nullable
A meta object containing non-standard meta-information about the error.
error.code enum<string> required
An application-specific error code, expressed as a string value.
Available options: INTERNALQUOTA_LIMITEDRATE_LIMITED
time integer
Default: 0
422 Unprocessable Entity
type string
Default: "ErrorResponse"
error object required
error.id string required
A unique identifier for this particular occurrence of the problem.
error.status integer required
The HTTP status code applicable to this problem, expressed as a string value.
error.detail string nullable
Explanation specific to this occurrence of the problem. Like title, this field’s value can be localized.
error.meta object nullable
A meta object containing non-standard meta-information about the error.
error.code enum<string> required
An application-specific error code, expressed as a string value.
Available options: INTERNALQUOTA_LIMITEDRATE_LIMITED
time integer
Default: 0
429 Too Many Requests
type string
Default: "ErrorResponse"
error object required
error.id string required
A unique identifier for this particular occurrence of the problem.
error.status integer required
The HTTP status code applicable to this problem, expressed as a string value.
error.detail string nullable
Explanation specific to this occurrence of the problem. Like title, this field’s value can be localized.
error.meta object nullable
A meta object containing non-standard meta-information about the error.
error.code enum<string> required
An application-specific error code, expressed as a string value.
Available options: INTERNALQUOTA_LIMITEDRATE_LIMITED
time integer
Default: 0