Library Reference¶

Brave Search Python Client supporting Web, Image, News and Video search.

class brave_search_python_client.BraveSearch(api_key: str | None = None)¶

A python client for the Brave Search API.

Provides access to all search types (web, images, news and videos).

async images(request: ImagesSearchRequest, retries: int = 0, wait_time: int = 2, dump_response: bool = False) → ImageSearchApiResponse¶

Execute an image search query using the Brave Search API.

Parameters:

request (ImagesSearchRequest) – Search request object with query parameters
retries (int) – Number of retries to be attempted in case of failure
wait_time (int) – Time to wait between retries
dump_response (bool) – Whether to dump the original response

Returns:

Top level response model for successful Image Search API requests

Return type:

ImageSearchApiResponse

Raises:

BraveSearchAPIError – If API request fails or returns an error

async static is_connected() → bool¶

Check if the Brave Search API is accessible. Important: This does not check if the API key is valid.

Returns:: True if API is accessible, False otherwise.
Return type:: bool

async news(request: NewsSearchRequest, retries: int = 0, wait_time: int = 2, dump_response: bool = False) → NewsSearchApiResponse¶

Execute a news search query using the Brave Search API.

Parameters:

request (NewsSearchRequest) – Search request object with query parameters
retries (int) – Number of retries to be attempted in case of failure
wait_time (int) – Time to wait between retries
dump_response (bool) – Whether to dump the original response

Returns:

Top level response model for successful News Search API requests

Return type:

NewsSearchApiResponse

Raises:

BraveSearchAPIError – If API request fails or returns an error

async videos(request: VideosSearchRequest, retries: int = 0, wait_time: int = 2, dump_response: bool = False) → VideoSearchApiResponse¶

Execute a video search query using the Brave Search API.

Parameters:

request (VideosSearchRequest) – Search request object with query parameters
retries (int) – Number of retries to be attempted in case of failure
wait_time (int) – Time to wait between retries
dump_response (bool) – Whether to dump the original response

Returns:

Top level response model for successful Video Search API requests

Return type:

VideoSearchApiResponse

Raises:

BraveSearchAPIError – If API request fails or returns an error

async web(request: WebSearchRequest, retries: int = 0, wait_time: int = 2, dump_response: bool = False) → WebSearchApiResponse¶

Execute a web search query using the Brave Search API.

For details see: https://api.search.brave.com/app/documentation/web-search/query

Parameters:

request (WebSearchRequest) – Search request object with query parameters
retries (int) – Number of retries to be attempted in case of failure
wait_time (int) – Time to wait between retries
dump_response (bool) – Whether to dump the original response

Returns:

Top level response model for successful Web Search API requests

Return type:

WebSearchApiResponse

Raises:

BraveSearchAPIError – If API request fails or returns an error

exception brave_search_python_client.BraveSearchAPIError¶: Error when accessing Brave Search API.

exception brave_search_python_client.BraveSearchClientError¶: Error when when interacting with Brave Search Python Client.

exception brave_search_python_client.BraveSearchError¶: Error when accessing.

class brave_search_python_client.CountryCode(*values)¶: Supported country codes for region-specific searches.

class brave_search_python_client.FreshnessType(*values)¶: Time-based filtering options for search results.

pydantic model brave_search_python_client.ImageSearchApiResponse¶

Top level response model for successful Image Search API requests.

The API can also respond back with an error response based on invalid subscription keys and rate limit events.

Fields:

query (brave_search_python_client.responses.image_search.Query)
results (list[brave_search_python_client.responses.image_search.ImageResult])
type (Literal['images'])

field query: Query [Required]¶: Image search query string

field results: list[ImageResult] [Required]¶: The list of image results for the given query

field type: Literal['images'] [Required]¶: The type of search API result. The value is always images

class brave_search_python_client.ImagesSafeSearchType(*values)¶: Image search content filtering levels.

pydantic model brave_search_python_client.ImagesSearchRequest¶

Defines the parameters useable in image search (see https://api.search.brave.com/app/documentation/image-search/query).

Fields:

count (int | None)
safesearch (brave_search_python_client.requests.ImagesSafeSearchType | None)

Validators:

field count: int | None = None¶

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

Constraints:

gt = 0
le = 100

field safesearch: ImagesSafeSearchType | None = None¶: The following values are supported: off: No filtering is done. strict: Drops all adult content from search results.

model_post_init(*args: object, **kwargs: object) → None¶: Initialize default values for optional image search parameters.

class brave_search_python_client.LanguageCode(*values)¶: Supported language codes for search results.

class brave_search_python_client.MarketCode(*values)¶: RFC 9110 market codes for region and language combinations.

class brave_search_python_client.NewsSafeSearchType(*values)¶: News search content filtering levels.

pydantic model brave_search_python_client.NewsSearchApiResponse¶

Top level response model for successful News Search API requests.

This model represents the complete structure of a successful API response, containing the query information and resulting news articles.

Note: The API can also respond back with an error response based on invalid subscription keys and rate limit events.

Fields:

query (brave_search_python_client.responses.news_search.Query)
results (list[brave_search_python_client.responses.news_search.NewsResult])
type (Literal['news'])

field query: Query [Required]¶: News search query string and related metadata

field results: list[NewsResult] [Required]¶: The list of news results for the given query

field type: Literal['news'] [Required]¶: The type of search API result. The value is always news

pydantic model brave_search_python_client.NewsSearchRequest¶

Defines the parameters useable in news search (see https://api.search.brave.com/app/documentation/news-search/query).

Fields:

count (int | None)
extra_snippets (bool | None)
freshness (str | None)
offset (int | None)
safesearch (brave_search_python_client.requests.NewsSafeSearchType | None)
ui_lang (brave_search_python_client.requests.MarketCode | None)

Validators:

validate_freshness » freshness

field count: int | None = None¶

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.

Constraints:

gt = 0
le = 50

field extra_snippets: bool | None = None¶: 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. Only available under Free AI, Base AI, Pro AI, Base Data, Pro Data and Custom plans.

field freshness: str | None = None¶

Filters search results by when they were discovered. Values: pd (24h), pw (7d), pm (31d), py (365d), or YYYY-MM-DDtoYYYY-MM-DD for custom range.

Validated by:

validate_freshness

field offset: int | None = None¶

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.

Constraints:

ge = 0
le = 9

field safesearch: NewsSafeSearchType | None = None¶: 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.

field ui_lang: MarketCode | None = None¶: User interface language preferred in response. Usually of the format <language_code>-<country_code>.

validator validate_freshness » freshness¶

Validate freshness parameter format and values.

Parameters:: v – The freshness value to validate.
Returns:: The validated freshness value.
Return type:: str | None

model_post_init(*args: object, **kwargs: object) → None¶: Initialize default values for optional news search parameters.

class brave_search_python_client.SearchType(*values)¶: Types of search requests.

class brave_search_python_client.UnitsType(*values)¶: Measurement unit system options.

pydantic model brave_search_python_client.VideoSearchApiResponse¶

Top level response model for successful Video Search API requests.

Contains the query information and a list of video results.

Fields:

query (brave_search_python_client.responses.video_search.Query)
results (list[brave_search_python_client.responses.video_search.VideoResult])
type (Literal['videos'])

field query: Query [Required]¶: Video search query string and related information

field results: list[VideoResult] [Required]¶: The list of video results for the given query

field type: Literal['videos'] [Required]¶: The type of search API result. Always ‘videos’

pydantic model brave_search_python_client.VideosSearchRequest¶

Defines the parameters useable in videos search (see https://api.search.brave.com/app/documentation/video-search/query).

Fields:

count (int | None)
freshness (str | None)
offset (int | None)
ui_lang (str | None)

Validators:

validate_freshness » freshness

field count: int | None = None¶

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.

Constraints:

gt = 0
le = 50

field freshness: str | None = None¶

Filters search results by when they were discovered. Values: pd (24h), pw (7d), pm (31d), py (365d), or YYYY-MM-DDtoYYYY-MM-DD for custom range.

Validated by:

validate_freshness

field offset: int | None = None¶

Constraints:

ge = 0
le = 9

field ui_lang: str | None = None¶: User interface language preferred in response. Usually of the format <language_code>-<country_code>.

validator validate_freshness » freshness¶

Validate freshness parameter format and values.

Parameters:: v – The freshness value to validate.
Returns:: The validated freshness value.
Return type:: str | None

model_post_init(*args: object, **kwargs: object) → None¶: Initialize default values for optional video search parameters.

class brave_search_python_client.WebSafeSearchType(*values)¶: Web search content filtering levels.

pydantic model brave_search_python_client.WebSearchApiResponse¶

Top level response model for successful Web Search API requests.

Fields:

discussions (brave_search_python_client.responses.web_search.Discussions | None)
faq (brave_search_python_client.responses.web_search.FAQ | None)
infobox (brave_search_python_client.responses.web_search.GraphInfobox | None)
locations (brave_search_python_client.responses.web_search.Locations | None)
mixed (brave_search_python_client.responses.web_search.MixedResponse | None)
news (brave_search_python_client.responses.web_search.News | None)
query (brave_search_python_client.responses.web_search.Query | None)
summarizer (brave_search_python_client.responses.web_search.Summarizer | None)
type (Literal['search'])
videos (brave_search_python_client.responses.web_search.Videos | None)
web (brave_search_python_client.responses.web_search.Search | None)

field discussions: Discussions | None = None¶: Discussions clusters from forum posts

field faq: FAQ | None = None¶: Frequently asked questions relevant to the query

field infobox: GraphInfobox | None = None¶: Aggregated information on an entity as infobox

field locations: Locations | None = None¶: Places of interest relevant to location queries

field mixed: MixedResponse | None = None¶: Preferred ranked order of search results

field news: News | None = None¶: News results relevant to the query

field query: Query | None = None¶: Search query string and its modifications

field summarizer: Summarizer | None = None¶: Summary key to get summary results

field type: Literal['search'] [Required]¶: The type of web search API result

field videos: Videos | None = None¶: Videos relevant to the query

field web: Search | None = None¶: Web search results relevant to the query

pydantic model brave_search_python_client.WebSearchRequest¶

Defines the parameters useable in web search (https://api.search.brave.com/app/documentation/web-search/query).

Fields:

count (int | None)
extra_snippets (bool | None)
freshness (str | None)
goggles_id (str | None)
offset (int | None)
result_filter (str | None)
safesearch (brave_search_python_client.requests.WebSafeSearchType | None)
summary (bool | None)
text_decorations (bool | None)
ui_lang (brave_search_python_client.requests.MarketCode | None)
units (brave_search_python_client.requests.UnitsType | None)

Validators:

validate_freshness » freshness
validate_result_filter » result_filter

field count: int | None = None¶

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.

Constraints:

gt = 0
le = 20

field extra_snippets: bool | None = None¶: 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. Only available under Free AI, Base AI, Pro AI, Base Data, Pro Data and Custom plans.

field freshness: str | None = None¶

Filters search results by when they were discovered. Values: pd (24h), pw (7d), pm (31d), py (365d), or YYYY-MM-DDtoYYYY-MM-DD for custom range.

Validated by:

validate_freshness

field goggles_id: str | None = None¶: Goggles act as a custom re-ranking on top of Brave’s search index. For more details, refer to the Goggles repository (https://github.com/brave/goggles-quickstart).

field offset: int | None = None¶

Constraints:

ge = 0
le = 9

field result_filter: str | None = None¶

A comma delimited string of result types to include in the search response. Available values are: discussions, faq, infobox, news, query, summarizer, videos, web, locations.

Validated by:

validate_result_filter

field safesearch: WebSafeSearchType | None = None¶: 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.

field summary: bool | None = None¶: This parameter enables summary key generation in web search results. This is required for summarizer to be enabled.

field text_decorations: bool | None = None¶: Whether display strings (e.g. result snippets) should include decoration markers (e.g. highlighting characters).

field ui_lang: MarketCode | None = None¶

User interface language preferred in response.

Constraints:

min_length = 5
max_length = 5

field units: UnitsType | None = None¶: The measurement units. If not provided, units are derived from search country. Possible values are: - metric: The standardized measurement system - imperial: The British Imperial system of units.

validator validate_freshness » freshness¶

Validate freshness parameter format and values.

Parameters:: v – The freshness value to validate.
Returns:: The validated freshness value.
Return type:: str | None

validator validate_result_filter » result_filter¶

Validate that result filter contains only valid WebResultType values.

Parameters:: v – The result filter string to validate.
Returns:: The validated result filter.
Return type:: str | None

model_post_init(*args: object, **kwargs: object) → None¶: Initialize default values for optional web search parameters.