Brave Web Search API

Response Objects

# WebSearchApiResponse

Top level response model for successful Web Search API requests. The response will include the relevant keys based on the plan subscribed, query relevance or applied result_filter as a query parameter. The API can also respond back with an error response based on invalid subscription keys and rate limit events.

Field	Type	Description
type	"search"	The type of web search API result. The value is always search.
discussions	Discussions	Discussions clusters aggregated from forum posts that are relevant to the query.
faq	FAQ	Frequently asked questions that are relevant to the search query.
infobox	GraphInfobox	Aggregated information on an entity showable as an infobox.
locations	Locations	Places of interest (POIs) relevant to location sensitive queries.
mixed	MixedResponse	Preferred ranked order of search results.
news	News	News results relevant to the query.
query	Query	Search query string and its modifications that are used for search.
videos	Videos	Videos relevant to the query.
web	Search	Web search results relevant to the query.
summarizer	Summarizer	Summary key to get summary results for the query.

# LocalPoiSearchApiResponse

Top level response model for successful Local Search API request to get extra information for locations. The response will include a list of location results corresponding to the ids in the request. The API can also respond back with an error response in cases like too many ids being requested, invalid subscription keys, and rate limit events. Access to Local Search API requires a subscription to a Pro plan.

Field	Type	Description
type	"local_pois"	The type of local POI search API result. The value is always local_pois.
results	list [ LocationResult ]	Location results matching the ids in the request.

# LocalDescriptionsSearchApiResponse

Top level response model for successful Local Search API request to get AI generated description for locations. The response includes a list of generated descriptions corresponding to the ids in the request. The API can also respond back with an error response in cases like too many ids being requested, invalid subscription keys, and rate limit events. Access to Local Search API requires a subscription to a Pro plan.

Field	Type	Description
type	"local_descriptions"	The type of local description search API result. The value is always local_descriptions.
results	list [ LocationDescription ]	Location descriptions matching the ids in the request.

# Query

A model representing information gathered around the requested query.

Field	Type	Description
original	string	The original query that was requested.
show_strict_warning	bool	Whether there is more content available for query, but the response was restricted due to safesearch.
altered	string	The altered query for which the search was performed.
safesearch	bool	Whether safesearch was enabled.
is_navigational	bool	Whether the query is a navigational query to a domain.
is_geolocal	bool	Whether the query has location relevance.
local_decision	string	Whether the query was decided to be location sensitive.
local_locations_idx	int	The index of the location.
is_trending	bool	Whether the query is trending.
is_news_breaking	bool	Whether the query has news breaking articles relevant to it.
ask_for_location	bool	Whether the query requires location information for better results.
language	Language	The language information gathered from the query.
spellcheck_off	bool	Whether the spellchecker was off.
country	string	The country that was used.
bad_results	bool	Whether there are bad results for the query.
should_fallback	bool	Whether the query should use a fallback.
lat	string	The gathered location latitutde associated with the query.
long	string	The gathered location longitude associated with the query.
postal_code	string	The gathered postal code associated with the query.
city	string	The gathered city associated with the query.
state	string	The gathered state associated with the query.
header_country	string	The country for the request origination.
more_results_available	bool	Whether more results are available for the given query.
custom_location_label	string	Any custom location labels attached to the query.
reddit_cluster	string	Any reddit cluster associated with the query.

# Discussions

A model representing a discussion cluster relevant to the query.

Field	Type	Description
type	"search"	The type identifying a discussion cluster. Currently the value is always search.
results	list [ DiscussionResult ]	A list of discussion results.
mutated_by_goggles	bool	Whether the discussion results are changed by a Goggle. False by default.

# DiscussionResult (SearchResult)

A discussion result. These are forum posts and discussions that are relevant to the search query.

Field	Type	Description
type	"discussion"	The discussion result type identifier. The value is always discussion.
data	ForumData	The enriched aggregated data for the relevant forum post.

# ForumData

Defines a result from a discussion forum.

Field	Type	Description
forum_name	string	The name of the forum.
num_answers	int	The number of answers to the post.
score	string	The score of the post on the forum.
title	string	The title of the post on the forum.
question	string	The question asked in the forum post.
top_comment	string	The top-rated comment under the forum post.

# FAQ

Frequently asked questions relevant to the search query term.

Field	Type	Description
type	"faq"	The FAQ result type identifier. The value is always faq.
results	list [ QA ]	A list of aggregated question answer results relevant to the query.

# QA

A question answer result.

Field	Type	Description
question	string	The question being asked.
answer	string	The answer to the question.
title	string	The title of the post.
url	string	The url pointing to the post.
meta_url	MetaUrl	Aggregated information about the url.

# MetaUrl

Aggregated information about a url.

Field	Type	Description
scheme	string	The protocol scheme extracted from the url.
netloc	string	The network location part extracted from the url.
hostname	string	The lowercased domain name extracted from the url.
favicon	string	The favicon used for the url.
path	string	The hierarchical path of the url useful as a display string.

# Search

A model representing a collection of web search results.

Field	Type	Description
type	"search"	A type identifying web search results. The value is always search.
results	list [ SearchResult ]	A list of search results.
family_friendly	bool	Whether the results are family friendly.

# SearchResult (Result)

Aggregated information on a web search result, relevant to the query.

Field	Type	Description
type	"search_result"	A type identifying a web search result. The value is always search_result.
subtype	"generic"	A sub type identifying the web search result type.
deep_results	DeepResult	Gathered information on a web search result.
schemas	list [ list ]	A list of schemas extracted from the web search result.
meta_url	MetaUrl	Aggregated information on the url associated with the web search result.
thumbnail	Thumbnail	The thumbnail of the web search result.
age	string	A string representing the age of the web search result.
language	string	The main language on the web search result.
location	LocationResult	The location details if the query relates to a restaurant.
video	VideoData	The video associated with the web search result.
movie	MovieData	The movie associated with the web search result.
faq	FAQ	Any frequently asked questions associated with the web search result.
qa	QAPage	Any question answer information associated with the web search result page.
book	Book	Any book information associated with the web search result page.
rating	Rating	Rating found for the web search result page.
article	Article	An article found for the web search result page.
product	ProductReview	The main product and a review that is found on the web search result page.
product_cluster	list [ ProductReview ]	A list of products and reviews that are found on the web search result page.
cluster_type	string	A type representing a cluster. The value can be product_cluster.
cluster	list [ Result ]	A list of web search results.
creative_work	CreativeWork	Aggregated information on the creative work found on the web search result.
music_recording	MusicRecording	Aggregated information on music recording found on the web search result.
review	Review	Aggregated information on the review found on the web search result.
software	Software	Aggregated information on a software product found on the web search result page.
recipe	Recipe	Aggregated information on a recipe found on the web search result page.
organization	Organization	Aggregated information on a organization found on the web search result page.
content_type	string	The content type associated with the search result page.
extra_snippets	list [ string ]	A list of extra alternate snippets for the web search result.

# Result

A model representing a web search result.

Field	Type	Description
title	string	The title of the web page.
url	string	The url where the page is served.
is_source_local	bool
is_source_both	bool
description	string	A description for the web page.
page_age	string	A date representing the age of the web page.
page_fetched	string	A date representing when the web page was last fetched.
profile	Profile	A profile associated with the web page.
language	string	A language classification for the web page.
family_friendly	bool	Whether the web page is family friendly.

# AbstractGraphInfobox (Result)

Shared aggregated information on an entity from a knowledge graph.

Field	Type	Description
type	"infobox"	The infobox result type identifier. The value is always infobox.
position	int	The position on a search result page.
label	string	Any label associated with the entity.
category	string	Category classification for the entity.
long_desc	string	A longer description for the entity.
thumbnail	Thumbnail	The thumbnail associated with the entity.
attributes	list [ list [ string ] ]	A list of attributes about the entity.
profiles	list [ Profile ] | list [ DataProvider ]	The profiles associated with the entity.
website_url	string	The official website pertaining to the entity.
ratings	list [ Rating ]	Any ratings given to the entity.
providers	list [ DataProvider ]	A list of data sources for the entity.
distance	Unit	A unit representing quantity relevant to the entity.
images	list [ Thumbnail ]	A list of images relevant to the entity.
movie	MovieData	Any movie data relevant to the entity. Appears only when the result is a movie.

# GenericInfobox (AbstractGraphInfobox)

Aggregated information on a generic entity from a knowledge graph.

Field	Type	Description
subtype	"generic"	The infobox subtype identifier. The value is always generic.
found_in_urls	list [ string ]	List of urls where the entity was found.

# EntityInfobox (AbstractGraphInfobox)

Aggregated information on an entity from a knowledge graph.

Field	Type	Description
subtype	"entity"	The infobox subtype identifier. The value is always entity.

# QAInfobox (AbstractGraphInfobox)

A question answer infobox.

Field	Type	Description
subtype	"code"	The infobox subtype identifier. The value is always code.
data	QAPage	The question and relevant answer.
meta_url	MetaUrl	Detailed information on the page containing the question and relevant answer.

# InfoboxWithLocation (AbstractGraphInfobox)

An infobox with location.

Field	Type	Description
subtype	"location"	The infobox subtype identifier. The value is always location.
is_location	bool	Whether the entity a location.
coordinates	list [ float ]	The coordinates of the location.
zoom_level	int	The map zoom level.
location	LocationResult	The location result.

# InfoboxPlace (AbstractGraphInfobox)

An infobox for a place, such as a business.

Field	Type	Description
subtype	"place"	The infobox subtype identifier. The value is always place.
location	LocationResult	The location result.

# GraphInfobox

Aggregated information on an entity shown as an infobox.

Field	Type	Description
type	"graph"	The type identifier for infoboxes. The value is always graph.
results	GenericInfoboxQAInfoboxInfoboxPlaceInfoboxWithLocationEntityInfobox	A list of infoboxes associated with the query.

# QAPage

Aggreated result from a question answer page.

Field	Type	Description
question	string	The question that is being asked.
answer	Answer	An answer to the question.

# Answer

A response representing an answer to a question on a forum.

Field	Type	Description
text	string	The main content of the answer.
author	string	The name of the author of the answer.
upvoteCount	int	Number of upvotes on the answer.
downvoteCount	int	The number of downvotes on the answer.

# Thumbnail

Aggregated details representing a picture thumbnail.

Field	Type	Description
src	string	The served url of the picture thumbnail.
original	string	The original url of the image.

# LocationWebResult (Result)

A model representing a web result related to a location.

Field	Type	Description
meta_url	MetaUrl	Aggregated information about the url.

# LocationResult (Result)

A result that is location relevant.

Field	Type	Description
type	"location_result"	Location result type identifier. The value is always location_result.
id	string	A Temporary id associated with this result, which can be used to retrieve extra information about the location. It remains valid for 8 hours..
provider_url	string	The complete url of the provider.
coordinates	list [ float ]	A list of coordinates associated with the location. This is a lat long represented as a floating point.
zoom_level	int	The zoom level on the map.
thumbnail	Thumbnail	The thumbnail associated with the location.
postal_address	PostalAddress	The postal address associated with the location.
opening_hours	OpeningHours	The opening hours, if it is a business, associated with the location .
contact	Contact	The contact of the business associated with the location.
price_range	string	A display string used to show the price classification for the business.
rating	Rating	The ratings of the business.
distance	Unit	The distance of the location from the client.
profiles	list [ DataProvider ]	Profiles associated with the business.
reviews	Reviews	Aggregated reviews from various sources relevant to the business.
pictures	PictureResults	A bunch of pictures associated with the business.
action	Action	An action to be taken.
serves_cuisine	list [ string ]	A list of cuisine categories served.
categories	list [ string ]	A list of categories.
icon_category	string	An icon category.
results	LocationWebResult	Web results related to this location.
timezone	string	IANA timezone identifier.
timezone_offset	string	The utc offset of the timezone.

# LocationDescription

AI generated description of a location result.

Field	Type	Description
type	"local_description"	The type of a location description. The value is always local_description.
id	string	A Temporary id of the location with this description.
description	string	AI generated description of the location with the given id.

# Locations

A model representing location results.

Field	Type	Description
type	"locations"	Location type identifier. The value is always locations.
results	list [ LocationResult ]	An aggregated list of location sensitive results.

# MixedResponse

The ranking order of results on a search result page.

Field	Type	Description
type	"mixed"	The type representing the model mixed. The value is always mixed.
main	list [ ResultReference ]	The ranking order for the main section of the search result page.
top	list [ ResultReference ]	The ranking order for the top section of the search result page.
side	list [ ResultReference ]	The ranking order for the side section of the search result page.

# ResultReference

The ranking order of results on a search result page.

Field	Type	Description
type	string	The type of the result.
index	int	The 0th based index where the result should be placed.
all	bool	Whether to put all the results from the type at specific position.

# Videos

A model representing video results.

Field	Type	Description
type	videos	The type representing the videos. The value is always videos.
results	list [ VideoResult ]	A list of video results.
mutated_by_goggles	bool	Whether the video results are changed by a Goggle. False by default.

# News

A model representing news results.

Field	Type	Description
type	news	The type representing the news. The value is always news.
results	list [ NewsResult ]	A list of news results.
mutated_by_goggles	bool	Whether the news results are changed by a Goggle. False by default.

# NewsResult

A model representing news results.

Field	Type	Description
meta_url	MetaUrl	The aggregated information on the url representing a news result
source	string	The source of the news.
breaking	bool	Whether the news result is currently a breaking news.
thumbnail	Thumbnail	The thumbnail associated with the news result.
age	string	A string representing the age of the news article.
extra_snippets	list [ string ]	A list of extra alternate snippets for the news search result.

# PictureResults

A model representing a list of pictures.

Field	Type	Description
viewMoreUrl	string	A url to view more pictures.
results	list [ Thumbnail ]	A list of thumbnail results.

# Action

A model representing an action to be taken.

Field	Type	Description
type	string	The type representing the action.
url	string	A url representing the action to be taken.

# PostalAddress

A model representing a postal address of a location

Field	Type	Description
type	"PostalAddress"	The type identifying a postal address. The value is always PostalAddress.
country	string	The country associated with the location.
postalCode	string	The postal code associated with the location.
streetAddress	string	The street address associated with the location.
addressRegion	string	The region associated with the location. This is usually a state.
addressLocality	string	The address locality or subregion associated with the location.
displayAddress	string	The displayed address string.

# OpeningHours

Opening hours of a bussiness at a particular location.

Field	Type	Description
current_day	list [ DayOpeningHours ]	The current day opening hours. Can have two sets of opening hours.
days	list [ list [ DayOpeningHours ] ]	The opening hours for the whole week.

# DayOpeningHours

A model representing the opening hours for a particular day for a business at a particular location.

Field	Type	Description
abbr_name	string	A short string representing the day of the week.
full_name	string	A full string representing the day of the week.
opens	string	A 24 hr clock time string for the opening time of the business on a particular day.
closes	string	A 24 hr clock time string for the closing time of the business on a particular day.

# Contact

A model representing contact information for an entity.

Field	Type	Description
email	string	The email address.
telephone	string	The telephone number.

# DataProvider

A model representing the data provider associated with the entity.

Field	Type	Description
type	"external"	The type representing the source of data. This is usually external.
name	string	The name of the data provider. This can be a domain.
url	string	The url where the information is coming from.
long_name	string	The long name for the data provider.
img	string	The served url for the image data.

# Profile

A profile of an entity.

Field	Type	Description
name	string	The name of the profile.
long_name	string	The long name of the profile.
url	string	The original url where the profile is available.
img	string	The served image url representing the profile.

# Unit

A model representing a unit of measurement.

Field	Type	Description
value	float	The quantity of the unit.
units	string	The name of the unit associated with the quantity.

# MovieData

Aggregated data for a movie result.

Field	Type	Description
name	string	Name of the movie.
description	string	A short plot summary for the movie.
url	string	A url serving a movie profile page.
thumbnail	Thumbnail	A thumbnail for a movie poster.
release	string	The release date for the movie.
directors	list [ Person ]	A list of people responsible for directing the movie.
actors	list [ Person ]	A list of actors in the movie.
rating	Rating	Rating provided to the movie from various sources.
duration	string	The runtime of the movie. The format is HH:MM:SS.
genre	list [ string ]	List of genres in which the movie can be classified.
query	string	The query that resulted in the movie result.

# Thing

A model describing a generic thing.

Field	Type	Description
type	"thing"	A type identifying a thing. The value is always thing.
name	string	The name of the thing.
url	string	A url for the thing.
thumbnail	Thumbnail	Thumbnail associated with the thing.

# Person (Thing)

A model describing a person entity.

Field	Type	Description
type	"person"	A type identifying a person. The value is always person.

# Rating

The rating associated with an entity.

Field	Type	Description
ratingValue	float	The current value of the rating.
bestRating	float	Best rating received.
reviewCount	int	The number of reviews associated with the rating.
profile	Profile	The profile associated with the rating.
is_tripadvisor	bool	Whether the rating is coming from Tripadvisor.

# Book

A model representing a book result.

Field	Type	Description
title	string	The title of the book.
author	list [ Person ]	The author of the book.
date	string	The publishing date of the book.
price	Price	The price of the book.
pages	int	The number of pages in the book.
publisher	Person	The publisher of the book.
rating	Rating	A gathered rating from different sources associated with the book.

# Price

A model representing the price for an entity.

Field	Type	Description
price	string	The price value in a given currency.
price_currency	string	The current of the price value.

# Article

A model representing an article.

Field	Type	Description
author	list [ Person ]	The author of the article.
date	string	The date when the article was published.
publisher	Organization	The name of the publisher for the article.
thumbnail	Thumbnail	A thumbnail associated with the article.
isAccessibleForFree	bool	Whether the article is free to read or is behind a paywall.

# ContactPoint (Thing)

A way to contact an entity.

Field	Type	Description
type	"contact_point"	A type string identifying a contact point. The value is always contact_point.
telephone	string	The telephone number of the entity.
email	string	The email address of the entity.

# Organization (Thing)

An entity responsible for another entity.

Field	Type	Description
type	"organization"	A type string identifying an organization. The value is always organization.
contact_points	list [ ContactPoint ]	A list of contact points for the organization.

# HowTo

Aggregated information on a how to.

Field	Type	Description
text	string	The how to text.
name	string	A name for the how to.
url	string	A url associated with the how to.
image	list [ string ]	A list of image urls associated with the how to.

# Recipe

Aggregated information on a recipe.

Field	Type	Description
title	string	The title of the recipe.
description	string	The description of the recipe.
thumbnail	Thumbnail	A thumbnail associated with the recipe.
url	string	The url of the web page where the recipe was found.
domain	string	The domain of the web page where the recipe was found.
favicon	string	The url for the favicon of the web page where the recipe was found.
time	string	The total time required to cook the recipe.
prep_time	string	The preparation time for the recipe.
cook_time	string	The cooking time for the recipe.
ingredients	string	Ingredients required for the recipe.
instructions	list [ HowTo ]	List of instructions for the recipe.
servings	int	How many people the recipe serves.
calories	int	Calorie count for the recipe.
rating	Rating	Aggregated information on the ratings associated with the recipe.
recipeCategory	string	The category of the recipe.
recipeCuisine	string	The cuisine classification for the recipe.
video	VideoData	Aggregated information on the cooking video associated with the recipe.

# Product

A model representing a product.

Field	Type	Description
type	"Product"	A string representing a product type. The value is always product.
name	string	The name of the product.
price	string	The price of the product.
thumbnail	Thumbnail	A thumbnail associated with the product.
description	string	The description of the product.
offers	list [ Offer ]	A list of offers available on the product.
rating	Rating	A rating associated with the product.

# Offer

An offer associated with a product.

Field	Type	Description
url	string	The url where the offer can be found.
priceCurrency	string	The currency in which the offer is made.
price	string	The price of the product currently on offer.

# Review

A model representing a review for an entity.

Field	Type	Description
type	"review"	A string representing review type. This is always review.
name	string	The review title for the review.
thumbnail	Thumbnail	The thumbnail associated with the reviewer.
description	string	A description of the review (the text of the review itself).
rating	Rating	The ratings associated with the review.

# Reviews

The reviews associated with an entity.

Field	Type	Description
results	list [ TripAdvisorReview ]	A list of trip advisor reviews for the entity.
viewMoreUrl	string	A url to a web page where more information on the result can be seen.
reviews_in_foreign_language	bool	Any reviews available in a foreign language.

# TripAdvisorReview

A model representing a Tripadvisor review.

Field	Type	Description
title	string	The title of the review.
description	string	A description seen in the review.
date	string	The date when the review was published.
rating	Rating	A rating given by the reviewer.
author	Person	The author of the review.
review_url	string	A url link to the page where the review can be found.
language	string	The language of the review.

# CreativeWork

A creative work relevant to the query. An example can be enriched metadata for an app.

Field	Type	Description
name	string	The name of the creative work.
thumbnail	Thumbnail	A thumbnail associated with the creative work.
rating	Rating	A rating that is given to the creative work.

# MusicRecording

Result classified as a music label or a song.

Field	Type	Description
name	string	The name of the song or album.
thumbnail	Thumbnail	A thumbnail associated with the music.
rating	Rating	The rating of the music.

# Software

A model representing a software entity.

Field	Type	Description
name	string	The name of the software product.
author	string	The author of software product.
version	string	The latest version of the software product.
codeRepository	string	The code repository where the software product is currently available or maintained.
homepage	string	The home page of the software product.
datePublisher	string	The date when the software product was published.
is_npm	bool	Whether the software product is available on npm.
is_pypi	bool	Whether the software product is available on pypi.
stars	int	The number of stars on the repository.
forks	int	The numbers of forks of the repository.
ProgrammingLanguage	string	The programming language spread on the software product.

# DeepResult

Aggregated deep results from news, social, videos and images.

Field	Type	Description
news	list [ NewsResult ]	A list of news results associated with the result.
buttons	list [ ButtonResult ]	A list of buttoned results associated with the result.
social	list [ KnowledgeGraphProfile ]	Social profile associated with the result.
videos	list [ VideoResult ]	Videos associated with the result.
images	list [ Image ]	Images associated with the result.

# VideoResult (Result)

A model representing a video result.

Field	Type	Description
type	"video_result"	The type identifying the video result. The value is always video_result.
video	VideoData	Meta data for the video.
meta_url	MetaUrl	Aggregated information on the URL
thumbnail	Thumbnail	The thumbnail of the video.
age	string	A string representing the age of the video.

# VideoData

A model representing metadata gathered for a video.

Field	Type	Description
duration	string	A time string representing the duration of the video. The format can be HH:MM:SS or MM:SS.
views	string	The number of views of the video.
creator	string	The creator of the video.
publisher	string	The publisher of the video.
thumbnail	Thumbnail	A thumbnail associated with the video.

# ButtonResult

A result which can be used as a button.

Field	Type	Description
type	"button_result"	A type identifying button result. The value is always button_result.
title	string	The title of the result.
url	string	The url for the button result.

# KnowledgeGraphEntity

Represents a knowledge graph entity.

Field	Type	Description
title	string	A short title describing the entity.
description	string	A description of the entity.
url	URL	The url representing the entity.
thumbnail	URL	The thumbnail associated with the entity.

# KnowledgeGraphProfile (KnowledgeGraphEntity)

Represents an entity profile from a knowledge graph.

Field	Type	Description
url	URL	The url representing the profile.
description	string	A description of the profile.

# URL

A model representing a URL.

Field	Type	Description
original	string	The original source URL.
display	string	The display URL.
alternatives	list [ string ]	An alternative representation of a URL.
canonical	string	The canonical form of the URL.
mobile	MobileUrlItem	A mobile friendly version of the URL.

# MobileUrlItem

A mobile friendly representation of the URL.

Field	Type	Description
original	string	The original source URL.
amp	string	The amp version of the URL.
android	string	An android friendly version of the URL.
ios	string	An ios friendly version of the URL.

# Image

A model describing an image

Field	Type	Description
thumbnail	Thumbnail	The thumbnail associated with the image.
url	string	The url of the image.
properties	ImageProperties	Metadata on the image.

# Language

A model representing a language.

Field	Type	Description
main	string	The main language seen in the string.

# ImageProperties

Metadata on an image.

Field	Type	Description
url	string	The image URL.

# TextLocation

Index based location in a text.

Field	Type	Description
start	int	The 0 based index, where the important part of the text starts.
end	int	The 0 based index, where the important part of the text ends.

# ReferenceSource

Index based location in a text for a particular reference.

Field	Type	Description
type	string	The type of search API result reference source.
name	string	The domain name of the source.
url	string	The url of the source.
img	string	The favicon url for the domain.
locations	list [ TextLocation ]	The location indices of the substring in the source text which is coming from the reference.

# Summarizer

Details on getting the summary.

Field	Type	Description
type	"summarizer"	The value is always summarizer.
key	string	The key for the summarizer API.