## Migrate from the Web Search API to the Web Search Tool

This guide shows you how to migrate from the deprecated [web search API endpoint](https://dev.writer.com/api-reference/tool-api/web-search) to the [web search tool](https://dev.writer.com/home/web-search-tool) in chat completions. After completing these steps, you can search the web using the web search tool, which provides the same capabilities within a chat completion workflow.

## Compare the APIs

The web search API and the web search tool provide similar search results, but the tool integrates web search into conversational workflows and requires specifying queries and configuration differently. The table below compares the two APIs.

| Aspect | Web search API | Web search tool |
| --- | --- | --- |
| **Endpoint** | `/v1/tools/web-search` | `/v1/chat` with the prebuilt [web search tool](https://dev.writer.com/home/web-search-tool) specification |
| **Request structure** | Pass search parameters such as `query`, `search_depth`, etc. directly in the request body | Provide the search query as part of the conversation `messages` and add the [web search tool](https://dev.writer.com/home/web-search-tool) in the `tools` array. Additional parameters (like domains to include or exclude) are specified in the tool configuration, not as direct request fields. |
| **Response format** | Results in `answer` and `sources` fields | Answer in `choices[0].message.content` and data in `web_search_data` field |
| **Parameter control** | Explicit API parameters | Most parameters specified in message prompt; only `include_domains` and `exclude_domains` as tool configuration |

## Migrate Your Code

The tabs below show a request using the web search API and the same request using the web search tool.

### Before: Web search API

The web search API accepts search parameters directly in the request body. The following example shows an example request using the web search API.

```bash
curl --location 'https://api.writer.com/v1/tools/web-search' \
  --header 'Content-Type: application/json' \
  --header "Authorization: Bearer $WRITER_API_KEY" \
  --data '{
    "query": "What are the most significant developments in artificial intelligence this year?",
    "include_domains": ["wikipedia.org", "github.com"],
    "exclude_domains": ["quora.com"],
    "search_depth": "advanced",
    "max_results": 10
  }'
```

### After: Web search tool

The web search tool uses the chat completions endpoint with a web search tool specification. The model handles the search based on your message and tool configuration. Parameters like `search_depth` and `max_results` are now specified in the message prompt:

```bash
curl --location 'https://api.writer.com/v1/chat' \
  --header 'Content-Type: application/json' \
  --header "Authorization: Bearer $WRITER_API_KEY" \
  --data '{
    "model": "palmyra-x5",
    "messages": [
      {
        "role": "user",
        "content": "What are the most significant developments in artificial intelligence this year? Use advanced search depth and limit to 10 results."
      }
    ],
    "tool_choice": "auto",
    "tools": [
      {
        "type": "web_search",
        "function": {
          "include_domains": ["wikipedia.org", "github.com"],
          "exclude_domains": ["quora.com"]
        }
      }
    ]
  }'
```

## Access Search Metadata

The web search tool response includes search metadata, including sources and raw text if requested, in the `web_search_data` field:

```python
from writerai import Writer

client = Writer()

messages = [{"role": "user", "content": "What are the most significant developments in artificial intelligence this year? Use advanced search depth and limit to 10 results."}]

tools = [{
  "type": "web_search",
  "function": {
    "include_domains": ["wikipedia.org", "github.com"],
    "exclude_domains": ["quora.com"]
  }
}]

response = client.chat.chat(
  model="palmyra-x5",
  messages=messages,
  tools=tools,
  tool_choice="auto"
)

# Get the search answer
answer = response.choices[0].message.content

# Get search metadata
search_metadata = response.choices[0].message.web_search_data
search_depth = search_metadata.search_depth
sources = search_metadata.sources

print(f"Answer: {answer}")
print(f"Search depth: {search_depth}")
print(f"Found {len(sources)} sources")

for source in sources:
    print(f"- {source.url}")
```

## Map Your Parameters

The following table shows how web search API parameters map to the web search tool. To customize search behavior in the web search tool, include your requirements in the message prompt.

| Web search API | Web search tool |
| --- | --- |
| `query` | Include in the message `content` field |
| `include_domains` | `tools[0].function.include_domains` |
| `exclude_domains` | `tools[0].function.exclude_domains` |
| `search_depth` | Include in the message prompt (for example, “perform an advanced search”) |
| `max_results` | Include in the message prompt (for example, “limit to 10 sources”) |
| `time_range` | Include in the message prompt (for example, “from the last week”) |
| `include_raw_content` | Include in the message prompt (for example, “include raw source text”) |
| `topic` | Include in the message prompt (for example, “search news articles”) |
| `country` | Include in the message prompt (for example, “localize results to the United States”) |
| `chunks_per_source` | Include in the message prompt (for example, “extract 3 text segments per source”) |