Brave Search

News Search

Search news content from a large independent index of web pages.

Authorization

x-subscription-token string header required

The subscription token that was generated for the product.

Request Body required

q string required

The user’s search query term. Query can not be empty. Maximum of 400 characters and 50 words in the query.

search_lang enum<string>

The search language preference. 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

country enum<string>

The search query country, where the results come from. The country string is limited to 2 character country codes of supported countries or ALL for worldwide.

Default: "US"

Available options: ARAUAT

safesearch enum<string>

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

off - No filtering is done.
moderate - Filter out explicit content.
strict - Filter out explicit and suggestive content.

Default: "strict"

Available options: offmoderatestrict

count integer

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

Min: 1 Max: 50 Default: 20

offset integer

The zero based offset that indicates number of search results per page (count) to skip before returning the result. The maximum is 9. The actual number delivered may be less than requested based on the query. In order to paginate results use this parameter together with count. For example, if your user interface displays 20 search results per page, set count to 20 and offset to 0 to show the first page of results. To get subsequent pages, increment offset by 1 (e.g. 0, 1, 2). The results may overlap across multiple pages.

Min: 0 Max: 9 Default: 0

spellcheck boolean

Whether to spell check the provided query. If the spellchecker 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

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

extra_snippets boolean nullable

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.

goggles string | string[] nullable

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.

include_fetch_metadata boolean

Include fetch metadata.

Default: false

operators boolean

Whether to apply search operators.

Default: true

Headers

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

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

Default: "news"

query object required

News search query string.

query.original string required

The original query that was requested.

query.altered string nullable

The altered query by the spellchecker. This is the query that is used to search if any.

query.cleaned string nullable

The cleaned normalized query by the spellchecker. This is the query that is used to search if any.

query.spellcheck_off boolean nullable

Whether the spellchecker is enabled or disabled.

query.show_strict_warning boolean nullable

The value is true if the lack of results is due to a strict safesearch setting. Adult content relevant to the query was found, but was blocked by safesearch.

query.search_operators object nullable

Search operators 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.

results object[]

The list of news results for the given query.

Default: []

results.type "news_result"

The type of news search API result. The value is always news_result.

Default: "news_result"

results.title string required

The title of the news article.

results.url string required

The source URL of the news article.

results.description string nullable

The description for the news article.

results.age string nullable

A human-readable representation of the news article’s age. For example, 2 days ago.

results.page_age string nullable

The page’s date, based on its published or last modified date.

results.page_fetched string nullable

The ISO date time when the page was last fetched. The format is YYYY-MM-DDTHH:MM:SSZ.

results.profile object nullable

A profile associated with the web page.

results.profile.name string required

The name of the profile.

results.profile.url string required

The original URL where the profile is available.

results.profile.long_name string nullable

The long name of the profile.

results.profile.img string nullable

The served image URL representing the profile.

results.fetched_content_timestamp integer nullable

The timestamp when the content was fetched.

results.meta_url object nullable

Aggregated information on the URL associated with the news search result.

results.meta_url.scheme string nullable

The protocol scheme extracted from the URL.

results.meta_url.netloc string nullable

The network location part extracted from the URL.

results.meta_url.hostname string nullable

The lowercased domain name extracted from the URL.

results.meta_url.favicon string nullable

The favicon used for the URL.

results.meta_url.path string nullable

The hierarchical path of the URL useful as a display string.

results.breaking boolean nullable

Whether the result includes breaking news.

results.thumbnail object nullable

The thumbnail for the news article.

results.thumbnail.src string required

The served URL of the thumbnail associated with the news article.

results.thumbnail.original string nullable

The original URL of the thumbnail associated with the news article.

results.extra_snippets string[] nullable

A list of extra alternate snippets for the news search result.

results.icons object[] nullable

Icons associated with the news result.

results.icons.href string required

results.icons.sizes string nullable required

results.icons.rel string nullable required

results.icons.type string nullable required

results.icons.ext string nullable required

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

curl -s --compressed -X 'POST' \
  'https://api.search.brave.com/res/v1/news/search' \
  -H 'accept: application/json' \
  -H "Accept-Encoding: gzip" \
  -H 'x-subscription-token: <YOUR_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
  "q": "machine learning",
  "country": "US",
  "search_lang": "en",
  "count": 20
}'