# Brave Search API
## Overview
Python wrapper for the [Brave Search API](https://brave.com/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
To get started, install the package using pip:
```bash
pip install brave-search
```
## 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.
```python
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:
```python
web_results = search_results.web_results
news_results = search_results.news_results
video_results = search_results.video_results
```
The module also supports asynchronous requests:
```python
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:
```python
from brave import Brave
query = "George Orwell, 1984"
num_results = 10
search_results = brave.search(q=query, raw=True)
```
## Features
### Download PDFs:
Use the `download_pdfs` method to download all PDFs found in the search results. This method returns a list of file paths to the downloaded PDFs. You can use Goggles to boost PDFs in your search results.
```python
from brave import Brave
brave = Brave()
query = "cobalt mining"
num_results = 10
search_results = brave.search(q=query, count=num_results)
search_results.download_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.
```python
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.
```python
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](https://search.brave.com/help/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.
```python
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:
```python
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
* Follow the instructions on the [official docs](https://python-poetry.org/docs/master/#installing-with-the-official-installer)
Once you have Poetry installed on your system simply run:
```bash
make init
```
## Developing
Check the [CONTRIBUTING.md](/CONTRIBUTING.md) for information about how to develop on this project.
Raw data
{
"_id": null,
"home_page": "https://github.com/kayvane1/brave-api",
"name": "brave-search",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.8",
"maintainer_email": null,
"keywords": "search, brave, api",
"author": "Kayvane Shakerifar",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/ba/5e/6fd4d7d7d88b16ba99a58fa3401824e2e004542325a3697ed7a0d9e5f955/brave_search-0.2.0.tar.gz",
"platform": null,
"description": "# Brave Search API\n\n## Overview\nPython wrapper for the [Brave Search API](https://brave.com/search/api/).\n\nBrave Search doesn\u2019t 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.\n\nThis repo is under active development, functionality may change.\nIf you have any suggestions or requests, please open an issue.\n\n## Installation\nTo get started, install the package using pip:\n\n```bash\npip install brave-search\n```\n\n## Usage\n\nThe 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.\n\n```python\n\nfrom brave import Brave\n\nbrave = Brave()\n\nquery = \"cobalt mining\"\nnum_results = 10\n\nsearch_results = brave.search(q=query, count=num_results)\n\n```\n\nThe `search_results` object will include all the data returned by the Brave Search API.\nYou can access `Web`, `News` and `Video` results from the websearch endpoint as follows:\n\n```python\nweb_results = search_results.web_results\nnews_results = search_results.news_results\nvideo_results = search_results.video_results\n```\n\nThe module also supports asynchronous requests:\n\n```python\n\nfrom brave import AsyncBrave\n\nbrave = AsyncBrave()\n\nquery = \"cobalt mining\"\nnum_results = 10\n\nsearch_results = await brave.search(q=query, count=num_results)\n```\n\nTo return the raw JSON response that has not been validated through the pydantic model use the `raw` flag:\n\n```python\n\nfrom brave import Brave\n\nquery = \"George Orwell, 1984\"\nnum_results = 10\n\nsearch_results = brave.search(q=query, raw=True)\n```\n\n## Features\n\n### Download PDFs:\n\nUse the `download_pdfs` method to download all PDFs found in the search results. This method returns a list of file paths to the downloaded PDFs. You can use Goggles to boost PDFs in your search results.\n\n```python\nfrom brave import Brave\n\nbrave = Brave()\n\nquery = \"cobalt mining\"\nnum_results = 10\n\nsearch_results = brave.search(q=query, count=num_results)\n\nsearch_results.download_pdfs()\n```\n\n### Aggregate Price Data\n\nUse 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.\n\n```python\n\n from brave import Brave\n\n brave = Brave()\n\n query = \"Blue Tack\"\n num_results = 10\n country = \"US\"\n search_results = brave.search(q=query, count=num_results, country=country)\n print(search_results.product_prices())\n # >> [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]\n print(search_results.product_price_ranges())\n # >> (4.99, 23.59)\n```\n\n### Aggregate Review Data\n\nUse 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.\n\n```python\n\nfrom brave import Brave\n\nbrave = Brave()\n\nquery = \"Blue Tack\"\nnum_results = 10\nsearch_results = brave.search(q=query, count=num_results)\nprint(search_results.average_product_review_score())\n# >> 88.13333333333333\n\n```\n\n### Goggles\n\nBrave is a powerful search engine that allows for the usage of `goggles` to rerank your search results to meet your use-case. [Goggles](https://search.brave.com/help/goggles) enable any individual\u2014or community of people\u2014to 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.\n\nHere we use a goggle which prioritizes academic and archival sources.\n\n```python\n\nfrom brave import Brave\n\nquery = \"cobalt mining\"\ngoggle_url = \"https://raw.githubusercontent.com/CSamuelAnderson/Brave-goggles/main/academic-and-archival.goggle\"\nnum_results = 10\nresult_filter = \"web\" # must be comma separated string\n\nsearch_results = brave.search(q=query, goggles_id=goggle_url, count=num_results, result_filter=result_filter)\n\n```\n\nYou can also make use of Goggles that have been directly contributed to this package:\n\n```python\n\nfrom brave import Brave\nfrom brave.goggles import thought_leadership\n\nquery = \"cobalt mining\"\nnum_results = 10\n\nsearch_results = brave.search(q=query, goggles_id=thought_leadership, count=num_results)\n```\n\n## Local Installation\n\nThis package uses Poetry for dependency management. To start developing here, you need to install Poetry\n\n* Follow the instructions on the [official docs](https://python-poetry.org/docs/master/#installing-with-the-official-installer)\n\nOnce you have Poetry installed on your system simply run:\n\n```bash\nmake init\n```\n\n## Developing\n\nCheck the [CONTRIBUTING.md](/CONTRIBUTING.md) for information about how to develop on this project.\n",
"bugtrack_url": null,
"license": null,
"summary": "Brave Search API wrapper",
"version": "0.2.0",
"project_urls": {
"Homepage": "https://github.com/kayvane1/brave-api",
"Repository": "https://github.com/kayvane1/brave-api"
},
"split_keywords": [
"search",
" brave",
" api"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "4722ae4784787fbb079bbabb5dc87387387c10428c29d8d191b8201dc387890c",
"md5": "bd6f38ab7ce3940c093c6198021b8ba6",
"sha256": "4ab0851434dba8781e4ab0e992ce09c7eae1c01d789faad601f4852eaff129d7"
},
"downloads": -1,
"filename": "brave_search-0.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "bd6f38ab7ce3940c093c6198021b8ba6",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.8",
"size": 41749,
"upload_time": "2024-04-27T15:40:21",
"upload_time_iso_8601": "2024-04-27T15:40:21.124923Z",
"url": "https://files.pythonhosted.org/packages/47/22/ae4784787fbb079bbabb5dc87387387c10428c29d8d191b8201dc387890c/brave_search-0.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "ba5e6fd4d7d7d88b16ba99a58fa3401824e2e004542325a3697ed7a0d9e5f955",
"md5": "fc727995d9266cb9c223a50548450de8",
"sha256": "4dd02e12e761bfbd50c1987d109142a0db2e1fa2d23b424b816f113f976dd309"
},
"downloads": -1,
"filename": "brave_search-0.2.0.tar.gz",
"has_sig": false,
"md5_digest": "fc727995d9266cb9c223a50548450de8",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.8",
"size": 28004,
"upload_time": "2024-04-27T15:40:22",
"upload_time_iso_8601": "2024-04-27T15:40:22.684692Z",
"url": "https://files.pythonhosted.org/packages/ba/5e/6fd4d7d7d88b16ba99a58fa3401824e2e004542325a3697ed7a0d9e5f955/brave_search-0.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-27 15:40:22",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "kayvane1",
"github_project": "brave-api",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "brave-search"
}
JSON
