Brave Search API
Overview
Python wrapper for the Brave Search API.
Brave Search doesn’t track you or your queries, it’s a privacy-preserving alternative to Google Search. It offers many endpoints for developers to build on top of. This module is a wrapper for the Brave Search API.
This repo is under active development, functionality may change.
If you have any suggestions or requests, please open an issue.
Installation
Brave Search supports Python 3.8 and newer. Install the package from PyPI with:
pip install brave-search
The package currently wraps Brave Search Web Search and Image Search. Web Search responses can include web, news, and video result groups, depending on the response returned by Brave.
Usage
The module supports both synchronous and asynchronous requests. Your Brave API key can either be passed as an environment variable under BRAVE_API_KEY or as an argument to the Brave class.
from brave import Brave
brave = Brave()
query = "cobalt mining"
num_results = 10
search_results = brave.search(q=query, count=num_results)
The search_results object will include all the data returned by the Brave Search API.
You can access Web, News and Video results from the websearch endpoint as follows:
web_results = search_results.web_results
news_results = search_results.news_results
video_results = search_results.video_results
The module also supports asynchronous requests:
from brave import AsyncBrave
brave = AsyncBrave()
query = "cobalt mining"
num_results = 10
search_results = await brave.search(q=query, count=num_results)
To return the raw JSON response that has not been validated through the pydantic model use the raw flag:
from brave import Brave
query = "George Orwell, 1984"
num_results = 10
search_results = brave.search(q=query, raw=True)
Image Search is available through the image method:
from brave import Brave
brave = Brave()
image_results = brave.image(q="cobalt mining")
Features
Download PDFs:
Use the download_all_pdfs method to download all PDFs found in the search results. You can use Goggles to boost PDFs in your search results.
from brave import Brave
brave = Brave()
query = "cobalt mining"
num_results = 10
search_results = brave.search(q=query, count=num_results)
search_results.download_all_pdfs()
Aggregate Price Data
Use the product_prices method to get a list of prices for a set of search results. This method returns a list of prices found in the search results. If no prices are found, an empty list is returned. This method does not currently support converting currencies.
from brave import Brave
brave = Brave()
query = "Blue Tack"
num_results = 10
country = "US"
search_results = brave.search(q=query, count=num_results, country=country)
print(search_results.product_prices())
# >> [6.28, 5.98, 4.99, 13.18, 6.59, 7.8, 5.56, 10.79, 5.02, 10.56, 16.95, 9.99, 23.59, 16.31, 11.96]
print(search_results.product_price_ranges())
# >> (4.99, 23.59)
Aggregate Review Data
Use the average_product_review_score method to get the average review score for a set of search results. This method converts all review scores to a 100 point scale.
from brave import Brave
brave = Brave()
query = "Blue Tack"
num_results = 10
search_results = brave.search(q=query, count=num_results)
print(search_results.average_product_review_score())
# >> 88.13333333333333
Goggles
Brave is a powerful search engine that allows for the usage of goggles to rerank your search results to meet your use-case. Goggles enable any individual—or community of people—to alter the ranking of Brave Search by using a set of instructions (rules and filters). Anyone can create, apply, or extend a Goggle. Essentially Goggles act as a custom re-ranking on top of the Brave search index.
Here we use a goggle which prioritizes academic and archival sources.
from brave import Brave
query = "cobalt mining"
goggle_url = "https://raw.githubusercontent.com/CSamuelAnderson/Brave-goggles/main/academic-and-archival.goggle"
num_results = 10
result_filter = "web" # must be comma separated string
search_results = brave.search(q=query, goggles_id=goggle_url, count=num_results, result_filter=result_filter)
You can also make use of Goggles that have been directly contributed to this package:
from brave import Brave
from brave.goggles import thought_leadership
query = "cobalt mining"
num_results = 10
search_results = brave.search(q=query, goggles_id=thought_leadership, count=num_results)
Local Installation
This package uses Poetry for dependency management. To start developing here, you need to install Poetry
Once you have Poetry installed on your system simply run:
make init
Developing
Check the CONTRIBUTING.md for information about how to develop on this project.
评论