### Example Response with Extra Snippets Source: https://api-dashboard.search.brave.com/app/documentation/web-search/get-started Illustrates the structure of a search result when the extra_snippets parameter is enabled, showing the 'extra_snippets' property. ```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..." ] } ] } } ``` -------------------------------- ### Web Search with File Type Operator Source: https://api-dashboard.search.brave.com/app/documentation/web-search/get-started Refine search queries using operators like 'filetype:'. This example searches for PDF documents related to machine learning. Replace with your actual subscription token. ```curl curl "https://api.search.brave.com/res/v1/web/search?q=machine+learning+filetype:pdf" \ -H "X-Subscription-Token: " ``` -------------------------------- ### Web Search with Extra Snippets Enabled Source: https://api-dashboard.search.brave.com/app/documentation/web-search/get-started Enable the extra snippets feature to get additional excerpts from search results. Replace with your actual subscription token. ```curl curl "https://api.search.brave.com/res/v1/web/search?q=python+web+frameworks&extra_snippets=true" \ -H "X-Subscription-Token: " ``` -------------------------------- ### Location Result with ID Source: https://api-dashboard.search.brave.com/app/documentation/web-search/get-started Example of a location result from the web search endpoint, showing the 'id' field which is a temporary identifier used for fetching detailed POI information. ```json { "locations": { "results": [ { "id": "1520066f3f39496780c5931d9f7b26a6", "title": "Pangea Banquet Mediterranean Food", ... }, { "id": "d00b153c719a427ea515f9eacf4853a2", "title": "Park Mediterranean Grill", ... }, { "id": "4b943b378725432aa29f019def0f0154", "title": "The Halal Mediterranean Co.", ... } ] } } ``` -------------------------------- ### Enable Rich Data Callback Source: https://api-dashboard.search.brave.com/app/documentation/web-search/get-started Request rich data enrichments by setting `enable_rich_callback=1` in the web search query. This prepares the API to return a callback key for fetching rich results. ```bash curl "https://api.search.brave.com/res/v1/web/search?q=weather+in+munich&enable_rich_callback=1" \ -H "X-Subscription-Token: " ``` -------------------------------- ### Query Web Search for Locations Source: https://api-dashboard.search.brave.com/app/documentation/web-search/get-started Initiate a search for locations using the web search endpoint. This is the first step in retrieving local enrichment data. Include your API key in the request header. ```bash curl "https://api.search.brave.com/res/v1/web/search?q=greek+restaurants+in+san+francisco" \ -H "X-Subscription-Token: " ``` -------------------------------- ### Fetch Local POI Descriptions Source: https://api-dashboard.search.brave.com/app/documentation/web-search/get-started Obtain AI-generated descriptions for locations using their IDs. Similar to fetching POI details, this endpoint also accepts up to 20 location IDs. ```bash curl "https://api.search.brave.com/res/v1/local/descriptions?ids=1520066f3f39496780c5931d9f7b26a6&ids=d00b153c719a427ea515f9eacf4853a2" \ -H "X-Subscription-Token: " ``` -------------------------------- ### Paginate Web Search Results Source: https://api-dashboard.search.brave.com/app/documentation/web-search/get-started Request page 2 of web search results with up to 20 items per page. Ensure your API key is included in the request header. ```bash curl "https://api.search.brave.com/res/v1/web/search?q=open+source+projects&count=20&offset=1" \ -H "X-Subscription-Token: " ``` -------------------------------- ### Fetch Rich Results Source: https://api-dashboard.search.brave.com/app/documentation/web-search/get-started Use the 'callback_key' obtained from the 'rich' field in the web search response to fetch the actual rich data. This is a separate API call. ```bash curl "https://api.search.brave.com/res/v1/web/rich?callback_key=86d06abffc884e9ea281a40f62e0a5a6" \ -H "X-Subscription-Token: " ``` -------------------------------- ### Fetch Local POI Details Source: https://api-dashboard.search.brave.com/app/documentation/web-search/get-started Retrieve detailed information for specific Points of Interest (POIs) using their IDs obtained from the web search. The 'ids' parameter accepts up to 20 location IDs. ```bash curl "https://api.search.brave.com/res/v1/local/pois?ids=1520066f3f39496780c5931d9f7b26a6&ids=d00b153c719a427ea515f9eacf4853a2" \ -H "X-Subscription-Token: " ``` -------------------------------- ### Local Descriptions Endpoint Source: https://api-dashboard.search.brave.com/app/documentation/web-search/get-started Fetches AI-generated descriptions for Points of Interest (POIs) using their IDs. ```APIDOC ## GET /res/v1/local/descriptions ### Description Retrieves AI-generated descriptions for specified Points of Interest (POIs) using their unique 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 ```json curl "https://api.search.brave.com/res/v1/local/descriptions?ids=1520066f3f39496780c5931d9f7b26a6&ids=d00b153c719a427ea515f9eacf4853a2" \ -H "X-Subscription-Token: " ``` ``` -------------------------------- ### Web Search with Country and Language Targeting Source: https://api-dashboard.search.brave.com/app/documentation/web-search/get-started Perform a web search targeting German content from Germany. Replace with your actual subscription token. ```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 Endpoint Source: https://api-dashboard.search.brave.com/app/documentation/web-search/get-started The primary endpoint for performing web searches. Supports query parameters for pagination, safe search, and enabling rich data callbacks. ```APIDOC ## GET /res/v1/web/search ### Description Performs a web search query and returns relevant results. Supports various parameters to control the search behavior and enrichments. ### Method GET ### Endpoint /res/v1/web/search ### Parameters #### Query Parameters - **q** (string) - Required - The search query. - **count** (integer) - Optional - Maximum number of results per page (max 20, default 20). - **offset** (integer) - Optional - Starting position for results (0-based, max 9). - **safesearch** (string) - Optional - Controls adult content filtering. Options: `off`, `moderate` (default), `strict`. - **enable_rich_callback** (integer) - Optional - Set to `1` to enable rich data callbacks. ### Request Example ```json curl "https://api.search.brave.com/res/v1/web/search?q=open+source+projects&count=20&offset=1&safesearch=off&enable_rich_callback=1" \ -H "X-Subscription-Token: " ``` ### Response #### Success Response (200) - **query** (object) - Contains information about the original query and whether more results are available. - **original** (string) - The original search query. - **more_results_available** (boolean) - Indicates if more results are available for subsequent requests. - **rich** (object) - Present if `enable_rich_callback` is set and rich results are available. - **type** (string) - The type of rich data. - **hint** (object) - Contains information to fetch rich results. - **vertical** (string) - The vertical of the rich data. - **callback_key** (string) - A key to fetch the rich results from the rich endpoint. #### Response Example ```json { "query": { "original": "open source projects", "more_results_available": true }, "rich": { "type": "rich", "hint": { "vertical": "weather", "callback_key": "86d06abffc884e9ea281a40f62e0a5a6" } } } ``` ``` -------------------------------- ### Rich Data Callback Endpoint Source: https://api-dashboard.search.brave.com/app/documentation/web-search/get-started Fetches rich data results using a callback key obtained from the web search endpoint. ```APIDOC ## GET /res/v1/web/rich ### Description Retrieves rich data results for a query using a callback key obtained from the web search endpoint. ### Method GET ### Endpoint /res/v1/web/rich ### Parameters #### Query Parameters - **callback_key** (string) - Required - The callback key obtained from the `rich.hint.callback_key` field in the web search response. ### Request Example ```json curl "https://api.search.brave.com/res/v1/web/rich?callback_key=86d06abffc884e9ea281a40f62e0a5a6" \ -H "X-Subscription-Token: " ``` ``` -------------------------------- ### Check for More Results Source: https://api-dashboard.search.brave.com/app/documentation/web-search/get-started Inspect the 'more_results_available' field within the 'query' object of the response to determine if additional pages of results exist. Only request the next page if this field is true. ```json { "query": { "original": "open source projects", "more_results_available": true } } ``` -------------------------------- ### Web Search with Freshness Filtering Source: https://api-dashboard.search.brave.com/app/documentation/web-search/get-started Filter web search results to include only pages from the past week. Ensure you replace with your actual subscription token. ```curl curl "https://api.search.brave.com/res/v1/web/search?q=machine+learning+tutorials&freshness=pw" \ -H "X-Subscription-Token: " ``` -------------------------------- ### Rich Data Hint Source: https://api-dashboard.search.brave.com/app/documentation/web-search/get-started The 'rich' field in the web search response indicates the availability of rich data and provides a 'callback_key' for fetching it. The 'vertical' field specifies the type of rich data. ```json { "rich": { "type": "rich", "hint": { "vertical": "weather", "callback_key": "86d06abffc884e9ea281a40f62e0a5a6" } } } ``` -------------------------------- ### Local POIs Endpoint Source: https://api-dashboard.search.brave.com/app/documentation/web-search/get-started Retrieves detailed information about Points of Interest (POIs) using their IDs obtained from a web search. ```APIDOC ## GET /res/v1/local/pois ### Description Fetches detailed information for specified Points of Interest (POIs) using their unique 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 ```json curl "https://api.search.brave.com/res/v1/local/pois?ids=1520066f3f39496780c5931d9f7b26a6&ids=d00b153c719a427ea515f9eacf4853a2" \ -H "X-Subscription-Token: " ``` ``` -------------------------------- ### Web Search Source: https://api-dashboard.search.brave.com/app/documentation/web-search/get-started Performs a web search query, returning relevant results from the indexed web pages. Supports various filtering and targeting options. ```APIDOC ## Web Search API ### Description Performs a web search query against a comprehensive index of web pages. This API is designed for human consumption and can be enhanced with local and rich data enrichments. ### Method GET ### Endpoint /res/v1/web/search ### Parameters #### Query Parameters - **q** (string) - Required - The search query string. Supports search operators like quotes, minus, site:, and filetype:. - **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`). - **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. - **ui_lang** (string) - Optional - Sets the preferred language for response metadata. - **extra_snippets** (boolean) - Optional - If set to `true`, includes up to 5 additional excerpts per search result. ### Request Example ```http GET https://api.search.brave.com/res/v1/web/search?q=machine+learning+tutorials&freshness=pw&country=US&search_lang=en ``` ### Headers - **X-Subscription-Token**: - Required - Your API subscription key. ### Response #### Success Response (200) - **web.results** (array) - An array of search result objects, each containing `title`, `url`, `description`, and optionally `extra_snippets`. #### Response Example (with extra_snippets enabled) ```json { "web": { "results": [ { "title": "Example Search Result Title", "url": "https://example.com", "description": "This is the main snippet for the search result.", "extra_snippets": [ "First additional excerpt.", "Second additional excerpt." ] } ] } } ``` ``` === COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.