A fully typed Brave Search API wrapper, providing easy access to web search, local POI search, and automatic polling for web search summary feature.
npm install brave-searchA fully typed Brave Search API wrapper, providing easy access to web search, news search, image search, local POI search, and automatic polling for AI-generated web search summary feature.
Install the package using npm:
``shell`
npm install brave-search
If you prefer to use the jsr registry, you can add the package using the following commands:
`shell`
npx jsr add @tyr/brave-search
Import the package in your project:
`typescript`
import { BraveSearch } from "brave-search";
If you are using the jsr registry, import the package as follows:
`typescript`
import { BraveSearch } from "@tyr/brave-search/";
1. Obtain a Brave Search API key from Brave Search API Dashboard.
2. Install the package using one of the methods above.
3. Initialize the BraveSearch class:`
typescript`
const BRAVE_API_KEY = "your-api-key-here";
const braveSearch = new BraveSearch(BRAVE_API_KEY);
Perform a web search using the webSearch method. Your IDE will provide type hints for the parameters and return types.
`typescript`
const webSearchResults = await braveSearch.webSearch("How many stars there are in our galaxy?", {
count: 5,
safesearch: "off",
search_lang: "en",
country: "US",
text_decorations: false,
});
console.log(webSearchResults);
Get a summarized answer for a query using the getSummarizedAnswer method. This method returns an object containing summary and webSearch promises.
`typescript
const { summary, webSearch } = braveSearch.getSummarizedAnswer("How many stars there are in our galaxy?", {
count: 5, // Number of search results to return
safesearch: "off", // Optional: Filter for adult content (default is "moderate")
search_lang: "en", // Optional: Language of the search results (default is "en")
country: "US", // Optional: Country for the search results (default is "us")
text_decorations: false, // Optional: Whether to include text decorations (default is true)
spellcheck: false, // Optional: Whether to enable spellcheck (default is true)
extra_snippets: true, // Optional: Whether to include extra snippets (default is false)
});
// Wait for the web search results (almost immediately)
const webSearchResponse = await webSearch;
console.log("Web Search Response:", JSON.stringify(webSearchResponse, null, 2));
// Wait for the summarized answer (can take up to couple of seconds)
const summarizedAnswer = await summary;
console.log("Summarized Answer:", JSON.stringify(summarizedAnswer, null, 2));
`
Search for local points of interest using the localPoiSearch method.
`typescript`
const poiResults = await braveSearch.localPoiSearch(["poi_id1", "poi_id2"]);
console.log(poiResults);
Get descriptions for local points of interest using the localDescriptionsSearch method.
`typescript`
const descriptionResults = await braveSearch.localDescriptionsSearch(["poi_id1", "poi_id2"]);
console.log(descriptionResults);
Perform an image search using the imageSearch method. Your IDE will provide type hints for the parameters and return types.
`typescript`
const imageSearchResults = await braveSearch.imageSearch("Golden Gate Bridge", {
count: 5,
safesearch: "off",
search_lang: "en",
country: "US",
});
console.log(imageSearchResults);
Perform a News search using the 'newsSearch method. Your IDE will provide type hints for the parameters and return types.
``typescript`
const newsSearchResults = await braveSearch.newsSearch("Ghibli ChatGPT", {
count: 5, // Number of search results to return
search_lang: "en", // Optional: Language of the search results (default is "en")
extra_snippets: true, // Optional: Whether to include extra snippets (default is false)
});
console.log(newsSearchResults);
The library supports various search options as defined in the Brave Search API documentation. For a complete list of options and their descriptions, please refer to the Brave Search API Documentation.
The BraveSearch class supports configurable polling options for summarization. You can customize the polling interval and the maximum number of polling attempts by passing a PollingOptions object to the constructor.
`typescript`
const braveSearch = new BraveSearch(BRAVE_API_KEY, {
pollInterval: 1000, // (default is 500ms)
maxPollAttempts: 30, // (default is 20)
});
- The summary option and getSummarizedAnswer method are only available with the Brave "Data for AI pro" plan.
- For detailed information about API usage, rate limits, and pricing, please visit the Brave Search API Terms.
For detailed API reference, please refer to the Brave Search API Documentation.
- Web search
- Automatic summarization with polling
- Local POI search
- Local descriptions search
- Error handling for API requests
Contributions are welcome! Please feel free to submit a Pull Request.
This package maintains consistent versioning across both npm (package.json) and Deno (deno.json) configurations. To release a new version:
`shellRelease a new major version (1.0.0 -> 2.0.0)
npm run release:major
These commands will:
1. Update the version in package.json
2. Automatically sync the new version to deno.json using the sync-versions.js script
For CI/CD pipelines, you can also use the sync-versions.js script directly to ensure version consistency.
This project is licensed under the GNU General Public License v3.0 - see the LICENSE file for details.
This library is not officially associated with Brave Software. It is a third-party implementation of the Brave Search API.