### Filter Web Search by Freshness (Past Week) Source: https://api-dashboard.search.brave.com/app/documentation/web-search/get-started Use the `freshness` parameter to filter web search results by time. This example shows how to get results from the past week. ```curl curl "https://api.search.brave.com/res/v1/web/search?q=machine+learning+tutorials&freshness=pw" \ -H "X-Subscription-Token: " ``` -------------------------------- ### Paginate web search results Source: https://api-dashboard.search.brave.com/app/documentation/web-search/get-started Request specific pages of results using the `count` and `offset` parameters. The `count` parameter limits results per page (max 20), and `offset` specifies the starting position (0-based). ```bash curl "https://api.search.brave.com/res/v1/web/search?q=open+source+projects&count=20&offset=1" \ -H "X-Subscription-Token: " ``` -------------------------------- ### Target Web Search by Country and Language Source: https://api-dashboard.search.brave.com/app/documentation/web-search/get-started Customize web search results by specifying the target country and content language. This example searches for "nachhaltige energie" in German from Germany. ```curl curl "https://api.search.brave.com/res/v1/web/search?q=nachhaltige+energie&country=DE&search_lang=de" \ -H "X-Subscription-Token: " ``` -------------------------------- ### Web Search with Rich Data Enabled Source: https://api-dashboard.search.brave.com/app/documentation/web-search/get-started To enable rich data enrichments in your search results, make a request to the web search endpoint with the `enable_rich_callback=1` query parameter. This example shows how to search for 'weather in munich'. ```APIDOC ## Web Search with Rich Data Enabled ### Description This endpoint allows you to perform a web search and enable the retrieval of rich data enrichments. ### Method GET ### Endpoint /res/v1/web/search ### Query Parameters - **q** (string) - Required - The search query. - **enable_rich_callback** (integer) - Required - Set to `1` to enable rich data callbacks. ### Request Example ```bash curl "https://api.search.brave.com/res/v1/web/search?q=weather+in+munich&enable_rich_callback=1" \ -H "X-Subscription-Token: " ``` ### Response #### Success Response (200) - **rich** (object) - Contains information about rich results if available. - **type** (string) - The type of rich result. - **hint** (object) - Hints for fetching rich results. - **vertical** (string) - The vertical of the rich result (e.g., 'weather'). - **callback_key** (string) - A key to fetch the detailed rich results. #### Response Example ```json { "rich": { "type": "rich", "hint": { "vertical": "weather", "callback_key": "86d06abffc884e9ea281a40f62e0a5a6" } } } ``` ``` -------------------------------- ### Web Search API Response with Rich Field Source: https://api-dashboard.search.brave.com/app/documentation/web-search/get-started This is an example of the `rich` field that may appear in the Web Search API response when rich results are available for a query. It contains a `callback_key` for fetching detailed results. ```json { "rich": { "type": "rich", "hint": { "vertical": "weather", "callback_key": "86d06abffc884e9ea281a40f62e0a5a6" } } } ``` -------------------------------- ### Query Web Search for Locations Source: https://api-dashboard.search.brave.com/app/documentation/web-search/get-started Make a request to the web search endpoint with a location-based query to get a list of locations. Each location result includes an `id` field. ```curl curl "https://api.search.brave.com/res/v1/web/search?q=greek+restaurants+in+san+francisco" \ -H "X-Subscription-Token: " ``` -------------------------------- ### Fetch Rich Results using Callback Key Source: https://api-dashboard.search.brave.com/app/documentation/web-search/get-started Use this cURL command to fetch the detailed rich results by providing the `callback_key` obtained from the Web Search API response. Replace `` with your actual subscription token. ```bash curl "https://api.search.brave.com/res/v1/web/rich?callback_key=86d06abffc884e9ea281a40f62e0a5a6" \ -H "X-Subscription-Token: " ``` -------------------------------- ### Request Web Search with Rich Data Enabled Source: https://api-dashboard.search.brave.com/app/documentation/web-search/get-started Use this cURL command to make a request to the web search endpoint and enable rich data callbacks. Replace `` with your actual subscription token. ```bash curl "https://api.search.brave.com/res/v1/web/search?q=weather+in+munich&enable_rich_callback=1" \ -H "X-Subscription-Token: " ``` -------------------------------- ### Web Search with Freshness Filtering Source: https://api-dashboard.search.brave.com/app/documentation/web-search/get-started Perform a web search and filter results by freshness. You can use predefined options like 'Last 24 Hours', 'Last 7 Days', 'Last 31 Days', 'Last Year', or specify a custom date range. ```APIDOC ## GET /res/v1/web/search ### Description Performs a web search with optional freshness filtering. ### Method GET ### Endpoint /res/v1/web/search ### Parameters #### Query Parameters - **q** (string) - Required - The search query. - **freshness** (string) - Optional - Filters results by freshness. Accepted values: `pd` (Last 24 Hours), `pw` (Last 7 Days), `pm` (Last 31 Days), `py` (Last Year), or a custom date range (e.g., `2022-04-01to2022-07-30`). ### Request Example ```json { "example": "curl \"https://api.search.brave.com/res/v1/web/search?q=machine+learning+tutorials&freshness=pw\" \ -H \"X-Subscription-Token: \"" } ``` ### Response #### Success Response (200) - **web.results** (array) - Contains search results, each with properties like `title`, `url`, `description`, and potentially `extra_snippets`. #### Response Example ```json { "web": { "results": [ { "title": "Machine Learning Tutorials", "url": "https://example.com/ml-tutorial", "description": "A comprehensive guide to machine learning..." } ] } } ``` ``` -------------------------------- ### Fetch Rich Results using Callback Key Source: https://api-dashboard.search.brave.com/app/documentation/web-search/get-started After receiving a response from the web search endpoint that includes a `callback_key` in the `rich` field, you can use this key to fetch the detailed rich results. ```APIDOC ## Fetch Rich Results using Callback Key ### Description This endpoint allows you to fetch detailed rich results using a callback key obtained from a previous web search. ### Method GET ### Endpoint /res/v1/web/rich ### Query Parameters - **callback_key** (string) - Required - The callback key obtained from the web search response. ### Request Example ```bash curl "https://api.search.brave.com/res/v1/web/rich?callback_key=86d06abffc884e9ea281a40f62e0a5a6" \ -H "X-Subscription-Token: " ``` ``` -------------------------------- ### Search for PDF files using filetype operator Source: https://api-dashboard.search.brave.com/app/documentation/web-search/get-started Use the `filetype` search operator within the `q` parameter to find specific file types. Ensure your API key is included in the request headers. ```bash curl "https://api.search.brave.com/res/v1/web/search?q=machine+learning+filetype:pdf" \ -H "X-Subscription-Token: " ``` -------------------------------- ### Fetch Local POI Descriptions Source: https://api-dashboard.search.brave.com/app/documentation/web-search/get-started Retrieves AI-generated descriptions for specific Points of Interest (POIs) using their temporary IDs. ```APIDOC ## GET /res/v1/local/descriptions ### Description Fetches AI-generated descriptions for Points of Interest (POIs) using their temporary IDs. ### Method GET ### Endpoint /res/v1/local/descriptions ### Parameters #### Query Parameters - **ids** (array) - Required - Location IDs from the web search response (max 20). ### Request Example ``` curl "https://api.search.brave.com/res/v1/local/descriptions?ids=1520066f3f39496780c5931d9f7b26a6&ids=d00b153c719a427ea515f9eacf4853a2" \ -H "X-Subscription-Token: " ``` ``` -------------------------------- ### Web Search with Extra Snippets Enabled Source: https://api-dashboard.search.brave.com/app/documentation/web-search/get-started Enhance search results by enabling the 'extra_snippets' feature, which provides up to 5 additional excerpts per search result for a more comprehensive content preview. ```APIDOC ## GET /res/v1/web/search ### Description Performs a web search and enables the 'extra_snippets' feature to include additional excerpts with each search result. ### Method GET ### Endpoint /res/v1/web/search ### Parameters #### Query Parameters - **q** (string) - Required - The search query. - **extra_snippets** (boolean) - Optional - Set to `true` to enable extra snippets for each search result. ### Request Example ```json { "example": "curl \"https://api.search.brave.com/res/v1/web/search?q=python+web+frameworks&extra_snippets=true\" \ -H \"X-Subscription-Token: \"" } ``` ### Response #### Success Response (200) - **web.results** (array) - Contains search results. If `extra_snippets` is enabled, each result will include an `extra_snippets` property (array of strings). #### Response Example ```json { "web": { "results": [ { "title": "Python Web Frameworks", "url": "https://example.com/python-frameworks", "description": "Main snippet text...", "extra_snippets": [ "First additional excerpt from the page...", "Second additional excerpt from the page..." ] } ] } } ``` ``` -------------------------------- ### Web Search with Country and Language Targeting Source: https://api-dashboard.search.brave.com/app/documentation/web-search/get-started Customize web search results by specifying the target country and the language of the content to be searched, as well as the preferred UI language for metadata. ```APIDOC ## GET /res/v1/web/search ### Description Performs a web search with optional country and language targeting. ### Method GET ### Endpoint /res/v1/web/search ### Parameters #### Query Parameters - **q** (string) - Required - The search query. - **country** (string) - Optional - Targets results from a specific country using a 2-character country code (e.g., `DE` for Germany). - **search_lang** (string) - Optional - Filters results by the language of the content (e.g., `de` for German). - **ui_lang** (string) - Optional - Sets the preferred language for response metadata. ### Request Example ```json { "example": "curl \"https://api.search.brave.com/res/v1/web/search?q=nachhaltige+energie&country=DE&search_lang=de\" \ -H \"X-Subscription-Token: \"" } ``` ### Response #### Success Response (200) - **web.results** (array) - Contains search results filtered by the specified country and language. #### Response Example ```json { "web": { "results": [ { "title": "Nachhaltige Energie in Deutschland", "url": "https://example.com/de-energy", "description": "Information about sustainable energy in Germany..." } ] } } ``` ``` -------------------------------- ### Enable Extra Snippets in Web Search Source: https://api-dashboard.search.brave.com/app/documentation/web-search/get-started Add the `extra_snippets=true` parameter to retrieve up to 5 additional excerpts per search result for more context. ```curl curl "https://api.search.brave.com/res/v1/web/search?q=python+web+frameworks&extra_snippets=true" \ -H "X-Subscription-Token: " ``` -------------------------------- ### Fetch Local POI Descriptions Source: https://api-dashboard.search.brave.com/app/documentation/web-search/get-started Retrieve AI-generated descriptions for locations using the Local Descriptions API. Similar to fetching POI details, this endpoint uses the `ids` parameter. ```curl curl "https://api.search.brave.com/res/v1/local/descriptions?ids=1520066f3f39496780c5931d9f7b26a6&ids=d00b153c719a427ea515f9eacf4853a2" \ -H "X-Subscription-Token: " ``` -------------------------------- ### Fetch Local POI Details Source: https://api-dashboard.search.brave.com/app/documentation/web-search/get-started Retrieves detailed information for specific Points of Interest (POIs) using their temporary IDs obtained from a web search. ```APIDOC ## GET /res/v1/local/pois ### Description Fetches detailed information for Points of Interest (POIs) using their temporary IDs. ### Method GET ### Endpoint /res/v1/local/pois ### Parameters #### Query Parameters - **ids** (array) - Required - Location IDs from the web search response (max 20). - **search_lang** (string) - Optional - Search language preference (ISO 639-1, default: `en`). - **ui_lang** (string) - Optional - UI language for response (e.g., `en-US`). - **units** (string) - Optional - Measurement units: `metric` or `imperial`. ### Request Example ``` curl "https://api.search.brave.com/res/v1/local/pois?ids=1520066f3f39496780c5931d9f7b26a6&ids=d00b153c719a427ea515f9eacf4853a2" \ -H "X-Subscription-Token: " ``` ``` -------------------------------- ### Query Web Search for Locations Source: https://api-dashboard.search.brave.com/app/documentation/web-search/get-started Initiates a web search to find locations based on a query. The results may contain temporary IDs for these locations. ```APIDOC ## GET /res/v1/web/search ### Description Queries the web search endpoint to find locations. Results may include temporary IDs for POIs. ### Method GET ### Endpoint /res/v1/web/search ### Parameters #### Query Parameters - **q** (string) - Required - The search query, e.g., "greek restaurants in san francisco". ### Request Example ``` curl "https://api.search.brave.com/res/v1/web/search?q=greek+restaurants+in+san+francisco" \ -H "X-Subscription-Token: " ``` ### Response #### Success Response (200) - **locations.results** (array) - Contains a list of location objects, each with an `id` field. #### Response Example ```json { "locations": { "results": [ { "id": "1520066f3f39496780c5931d9f7b26a6", "title": "Pangea Banquet Mediterranean Food", ... } ] } } ``` ``` -------------------------------- ### Check for more results availability Source: https://api-dashboard.search.brave.com/app/documentation/web-search/get-started Determine if additional pages of results are available by checking the `more_results_available` field within the `query` object of the response. Only request the next page if this field is `true` to avoid unnecessary API calls. ```json { "query": { "original": "open source projects", "more_results_available": true } } ``` -------------------------------- ### Fetch Local POI Details Source: https://api-dashboard.search.brave.com/app/documentation/web-search/get-started Use the `id` values obtained from web search to fetch detailed POI information from the Local Search API. The `ids` query parameter accepts up to 20 location IDs. ```curl curl "https://api.search.brave.com/res/v1/local/pois?ids=1520066f3f39496780c5931d9f7b26a6&ids=d00b153c719a427ea515f9eacf4853a2" \ -H "X-Subscription-Token: " ``` -------------------------------- ### Web Search Result with Extra Snippets Source: https://api-dashboard.search.brave.com/app/documentation/web-search/get-started When `extra_snippets` is enabled, each result includes an `extra_snippets` array with alternative excerpts. This JSON shows the structure. ```json { "web": { "results": [ { "title": "Python Web Frameworks", "url": "https://example.com/python-frameworks", "description": "Main snippet text...", "extra_snippets": [ "First additional excerpt from the page...", "Second additional excerpt from the page...", "Third additional excerpt from the page..." ] } ] } } ``` === COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.