Skip to main content
GET
/
v1
/
news
/
search
{
  "type": "news",
  "query": {
    "original": "<string>",
    "altered": "<string>",
    "cleaned": "<string>",
    "spellcheck_off": true,
    "show_strict_warning": true,
    "search_operators": {
      "applied": false,
      "cleaned_query": "<string>",
      "sites": [
        "<string>"
      ]
    }
  },
  "results": []
}

Authorizations

​
x-subscription-token
string
header
required

The subscription token that was generated for the product.

Headers

​
x-subscription-token
string
required

The subscription token that was generated for the product.

Examples:

"BSAgdIxiH0OLq6fnx6F-xp8Yplv4uOp"

​
api-version
string | null

The API version to use. This is denoted by the format YYYY-MM-DD. Default is the latest that is available.

​
accept
enum<string>

The default supported media type is application/json.

Available options:
application/json,
*/*
​
cache-control
enum<string> | null

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.

Available options:
TitleConst
CacheControlno-cache
​
user-agent
string | null

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.

Examples:

"**Android** Mozilla/5.0 (Linux; Android 12) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/103.0.5060.71 Mobile Safari/537.36"

"**iOS** 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"

"**macOS** Mozilla/5.0 (Macintosh; Intel Mac OS X 12_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/103.0.0.0 Safari/537.36"

"**Windows** Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/103.0.0.0 Safari/537.36"

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.

Required string length: 1 - 400
​
search_lang
enum<string>

The search language preference. The 2 or more character language code for which the search results are provided.

Available options:
ar,
eu,
bn,
bg,
ca,
zh-hans,
zh-hant,
hr,
cs,
da,
nl,
en,
en-gb,
et,
fi,
fr,
gl,
de,
el,
gu,
he,
hi,
hu,
is,
it,
jp,
kn,
ko,
lv,
lt,
ms,
ml,
mr,
nb,
pl,
pt-br,
pt-pt,
pa,
ro,
ru,
sr,
sk,
sl,
es,
sv,
ta,
te,
th,
tr,
uk,
vi
​
ui_lang
enum<string>

User interface language preferred in response. Usually of the format <language_code>-<country_code>. For more, see RFC 9110.

Available options:
es-AR,
en-AU,
de-AT,
nl-BE,
fr-BE,
pt-BR,
en-CA,
fr-CA,
es-CL,
da-DK,
fi-FI,
fr-FR,
de-DE,
el-GR,
zh-HK,
en-IN,
en-ID,
it-IT,
ja-JP,
ko-KR,
en-MY,
es-MX,
nl-NL,
en-NZ,
no-NO,
zh-CN,
pl-PL,
en-PH,
ru-RU,
en-ZA,
es-ES,
sv-SE,
fr-CH,
de-CH,
zh-TW,
tr-TR,
en-GB,
en-US,
es-US
​
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.

Available options:
AR,
AU,
AT,
BE,
BR,
CA,
CL,
DK,
FI,
FR,
DE,
GR,
HK,
IN,
ID,
IT,
JP,
KR,
MY,
MX,
NL,
NZ,
NO,
CN,
PL,
PT,
PH,
RU,
SA,
ZA,
ES,
SE,
CH,
TW,
TR,
GB,
US,
ALL
​
safesearch
enum<string>

Filters search results for adult content. The following values are supported: off (No filtering), moderate (Filter out explicit content), strict (Filter out explicit and suggestive content). The default value is moderate

Available options:
off,
moderate,
strict
​
count
integer
default:20

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.

Required range: 1 <= x <= 100
​
offset
integer
default:0

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.

Required range: 0 <= x <= 9
​
spellcheck
boolean
default:true

Whether to spellcheck 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.

​
freshness
string
default:""

Filters search results by when they were discovered. The following values are supported: pd (Discovered within the last 24 hours), pw (Discovered within the last 7 Days), pm (Discovered within the last 31 Days), py (Discovered within the last 365 Days), YYYY-MM-DDtoYYYY-MM-DD (timeframe is also supported by specifying the date range e.g. 2022-04-01to2022-07-30).

​
extra_snippets
boolean | null

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

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, refer to the Goggles repository. The parameter can be repeated to query with multiple goggles.

​
include_fetch_metadata
boolean
default:false

Include fetch metadata

​
operators
boolean
default:true

Whether to apply search operators

Response

Successful Response

​
query
object
required

News search query string.

​
type
enum<string>
default:news
Available options:
TitleConst
Typenews
​
results
NewsResult · object[]

The list of news results for the given query.

⌘I