Skip to main content
POST
Web Search

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

​
accept
enum<string>
default:application/json

The default supported media type is application/json.

Available options:
application/json,
*/*
Example:

"application/json"

​
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. Read more about API versioning.

​
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:
no-cache
Allowed value: "no-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.

​
x-loc-city
string | null

The generic name of the client city.

​
x-loc-country
enum<string> | null

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

Available options:
AD,
AE,
AF,
AG,
AI,
AL,
AM,
AO,
AQ,
AR,
AS,
AT,
AU,
AW,
AX,
AZ,
BA,
BB,
BD,
BE,
BF,
BG,
BH,
BI,
BJ,
BL,
BM,
BN,
BO,
BQ,
BR,
BS,
BT,
BV,
BW,
BY,
BZ,
CA,
CC,
CD,
CF,
CG,
CH,
CI,
CK,
CL,
CM,
CN,
CO,
CR,
CU,
CV,
CW,
CX,
CY,
CZ,
DE,
DJ,
DK,
DM,
DO,
DZ,
EC,
EE,
EG,
EH,
ER,
ES,
ET,
FI,
FJ,
FK,
FM,
FO,
FR,
GA,
GB,
GD,
GE,
GF,
GG,
GH,
GI,
GL,
GM,
GN,
GP,
GQ,
GR,
GS,
GT,
GU,
GW,
GY,
HK,
HM,
HN,
HR,
HT,
HU,
ID,
IE,
IL,
IM,
IN,
IO,
IQ,
IR,
IS,
IT,
JE,
JM,
JO,
JP,
KE,
KG,
KH,
KI,
KM,
KN,
KP,
KR,
KW,
KY,
KZ,
LA,
LB,
LC,
LI,
LK,
LR,
LS,
LT,
LU,
LV,
LY,
MA,
MC,
MD,
ME,
MF,
MG,
MH,
MK,
ML,
MM,
MN,
MO,
MP,
MQ,
MR,
MS,
MT,
MU,
MV,
MW,
MX,
MY,
MZ,
NA,
NC,
NE,
NF,
NG,
NI,
NL,
NO,
NP,
NR,
NU,
NZ,
OM,
PA,
PE,
PF,
PG,
PH,
PK,
PL,
PM,
PN,
PR,
PS,
PT,
PW,
PY,
QA,
RE,
RO,
RS,
RU,
RW,
SA,
SB,
SC,
SD,
SE,
SG,
SH,
SI,
SJ,
SK,
SL,
SM,
SN,
SO,
SR,
SS,
ST,
SV,
SX,
SY,
SZ,
TC,
TD,
TF,
TG,
TH,
TJ,
TK,
TL,
TM,
TN,
TO,
TR,
TT,
TV,
TW,
TZ,
UA,
UG,
UM,
US,
UY,
UZ,
VA,
VC,
VE,
VG,
VI,
VN,
VU,
WF,
WS,
YE,
YT,
ZA,
ZM,
ZW
Example:

"US"

​
x-loc-lat
number | null

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.

Required range: -90 <= x <= 90
Example:

37.787

​
x-loc-long
number | null

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.

Required range: -180 <= x <= 180
Example:

-122.4

​
x-loc-postal-code
string | null

The client’s postal code.

​
x-loc-state
string | null

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.

Example:

"CA"

​
x-loc-state-name
string | null

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.

Example:

"California"

​
x-loc-timezone
string | null

The IANA timezone for the client’s device. For complete list of IANA timezones and location mappings see IANA Database and Geonames Database.

Body

application/json
​
q
string
required

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

Required string length: 1 - 600
​
country
enum<string>
default:US

The 2 character country code where the search results come from.

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
​
search_lang
enum<string>
default:en

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,
ja,
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>
default:en-US

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
​
count
integer
default:20

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.

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

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.

Required range: 0 <= x <= 9
​
safesearch
enum<string>
default:moderate

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.
Available options:
off,
moderate,
strict
Example:

""

​
spellcheck
boolean
default:true

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.

Examples:

""

true

false

​
freshness
string
default:""

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.
Examples:

""

"pm"

"2022-04-01to2022-07-30"

​
text_decorations
boolean
default:true

Whether display strings (e.g. result snippets) should include decoration markers (e.g. highlighting characters).

Examples:

""

true

false

​
result_filter
string[] | null

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.

Example:

""

​
units
enum<string> | null

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:
imperial,
metric
Example:

""

​
goggles_id
string | null
deprecated

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

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

Example:

""

​
summary
boolean | null

This parameter enables summary key generation in web search results. This is required for summarizer to be enabled.

Example:

""

​
enable_rich_callback
boolean
default:false

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.

Examples:

""

false

true

​
include_fetch_metadata
boolean
default:false

Include fetch metadata.

Examples:

""

false

true

​
operators
boolean
default:true

Whether to apply search operators

Examples:

""

true

false

Response

Successful Response

​
type
enum<string>
default:search
Available options:
search
Allowed value: "search"
​
query
Query · object | null

Search query string and its modifications that are used for search.

​
discussions
Discussions · object | null

Discussions clusters aggregated from forum posts that are relevant to the query.

​
faq
FAQ · object | null

Frequently asked questions that are relevant to the search query.

​
infobox
GraphInfobox · object | null

Aggregated information on an entity showable as an infobox.

​
locations
Locations · object | null

Places of interest (POIs) relevant to location sensitive queries.

​
mixed
MixedResponse · object | null

Preferred ranked order of search results.

​
news
News · object | null

News results relevant to the query.

​
videos
Videos · object | null

Videos results relevant to the query.

​
web
Search · object | null

Web results relevant to the query.

​
summarizer
Summarizer · object | null

Summary key to get summary results for the query.

​
rich
RichHeaderCallback · object | null

Callback information to retrieve rich results.