## Overview

The web search tool enables you to:

- Search for current information and news
- Find factual information from reliable sources
- Get real-time data that may not be in your model’s training data
- Filter results by domain, time range, and geographic location
- Control search depth and result comprehensiveness

## Request example

cURL

```bash
curl --location 'https://api.writer.com/v1/tools/web-search' \
    --header 'Content-Type: application/json' \
    --header "Authorization: Bearer $WRITER_API_KEY" \
    --data '{
        "query": "How do I get an API key for the Writer API?",
        "include_domains": ["dev.writer.com"]
    }'
```

Python

```python
from writerai import Writer

# Initialize the Writer client. If you don't pass the `api_key` parameter,
# the client looks for the `WRITER_API_KEY` environment variable.
client = Writer()

response = client.tools.web_search(
    query="How do I get an API key for the Writer API?",
    include_domains=["dev.writer.com"]
)

print(response.answer)
```

JavaScript

```javascript
import { Writer } from "writer-sdk";

// Initialize the Writer client. If you don't pass the `apiKey` parameter,
// the client looks for the `WRITER_API_KEY` environment variable.
const client = new Writer();

const response = await client.tools.webSearch({
    query: "How do I get an API key for the Writer API?",
    include_domains: ["dev.writer.com"]
});

console.log(response.answer);
```

### Request parameters

| Parameter               | Type       | Required | Description                                                                                  |
|-------------------------|------------|----------|----------------------------------------------------------------------------------------------|
| `query`                 | string     | Yes      | The search query to execute                                                                  |
| `topic`                 | string     | No       | The search topic category. Use `news` for current events and news articles, or `general` for broader web search. Default: `general` |
| `search_depth`          | string     | No       | Controls search comprehensiveness. Use `basic` for fewer but highly relevant results, or `advanced` for deeper search with more results. Default: `basic` |
| `chunks_per_source`     | integer    | No       | Only applies when `search_depth` is `advanced`. Specifies how many text segments to extract from each source. Limited to 3 chunks maximum |
| `max_results`           | integer    | No       | Limits the number of search results returned. Cannot exceed 20 sources                       |
| `time_range`            | string     | No       | Filters results to content published within the specified time range. Options: `day`, `week`, `month`, `year`, `d`, `w`, `m`, `y` |
| `days`                  | integer    | No       | For news topic searches, specifies how many days of news coverage to include                 |
| `include_raw_content`   | string  Boolean | No       | Controls how raw content is included. Options: `text`, `markdown`, `true` (same as markdown), `false` (not included). Default: `false` |
| `include_answer`        | Boolean    | No       | Whether to include a generated answer to the query in the response. Default: `true`         |
| `include_domains`       | array      | No       | Domains to include in the search                                                             |
| `exclude_domains`       | array      | No       | Domains to exclude from the search                                                             |
| `country`               | string     | No       | Localizes search results to a specific country. Only applies to general topic searches       |
| `stream`                | Boolean    | No       | Enables streaming of search results as they become available. Default: `false`              |

### Response format

The response contains the search query, generated answer if requested, and an array of sources with their URLs and raw content if requested.

| Parameter               | Type       | Description                                                                                   |
|-------------------------|------------|-----------------------------------------------------------------------------------------------|
| `query`                 | string     | The search query that was submitted                                                           |
| `answer`                | string     | Generated answer based on the search results. `null` if `include_answer` is `false`        |
| `sources`               | array      | The search results found                                                                      |
| `sources[].url`         | string     | URL of the search result                                                                       |
| `sources[].raw_content` | string     | Raw content from the source URL. `null` if `include_raw_content` is `false`                 |

## Best practices

- **Use specific queries**: More specific queries tend to yield better results
- **Choose appropriate topic**: Use `news` for current events and `general` for broader searches
- **Filter by domains**: Use `include_domains` and `exclude_domains` to focus on reliable sources
- **Control search depth**: Use `basic` for quick searches and `advanced` for comprehensive research
- **Set time ranges**: Use `time_range` to get current information when needed
- **Limit results**: Use `max_results` to control response size and processing time

## Next steps

Learn about other tools and capabilities available in the Writer API:

- [PDF parsing](https://dev.writer.com/api-reference/tool-api/pdf-parser)
- [Web search tool for chat completions](https://dev.writer.com/home/web-search-tool)
- [Tool calling](https://dev.writer.com/home/tool-calling)
- [Knowledge Graph queries](https://dev.writer.com/home/kg-query)