Implementation:Openai Openai python Web Search Preview Tool

Knowledge Sources	Openai_Openai_python OpenAI API Reference
Domains	API_Types, Responses_API
Last Updated	2026-02-15 00:00 GMT

Overview

Pydantic response model representing a web search preview tool returned by the OpenAI Responses API.

Description

WebSearchPreviewTool is a Pydantic BaseModel subclass that represents the web search tool configuration as it appears in API responses. When the Responses API returns a tool definition that includes web search, this model captures the tool's type, its search_context_size setting, and an optional UserLocation object describing the caller's approximate geographic location. The nested UserLocation model holds optional fields for city, country (ISO 3166-1 two-letter code), region, and timezone (IANA format), along with a required type literal fixed to "approximate".

Usage

Import WebSearchPreviewTool when you need to type-annotate or inspect the web search tool object that the API returns inside a response's tool list. It is the response-side counterpart to WebSearchToolParam (the request-side TypedDict).

Code Reference

Source Location

• Repository: openai-python
• File: src/openai/types/responses/web_search_preview_tool.py

Signature

class UserLocation(BaseModel):
    """The user's location."""
    type: Literal["approximate"]
    city: Optional[str] = None
    country: Optional[str] = None
    region: Optional[str] = None
    timezone: Optional[str] = None

class WebSearchPreviewTool(BaseModel):
    """This tool searches the web for relevant results to use in a response."""
    type: Literal["web_search_preview", "web_search_preview_2025_03_11"]
    search_context_size: Optional[Literal["low", "medium", "high"]] = None
    user_location: Optional[UserLocation] = None

Import

from openai.types.responses import WebSearchPreviewTool

I/O Contract

WebSearchPreviewTool Fields

Name	Type	Required	Description
type	Literal["web_search_preview", "web_search_preview_2025_03_11"]	Yes	The type of the web search tool. One of "web_search_preview" or "web_search_preview_2025_03_11".
search_context_size	Optional[Literal["low", "medium", "high"]]	No	Guidance for the amount of context window space to use for the search. Defaults to "medium".
user_location	Optional[UserLocation]	No	The user's approximate geographic location used to localize search results.

UserLocation Fields

Name	Type	Required	Description
type	Literal["approximate"]	Yes	The type of location approximation. Always "approximate".
city	Optional[str]	No	Free text city name, e.g. "San Francisco".
country	Optional[str]	No	Two-letter ISO 3166-1 country code, e.g. "US".
region	Optional[str]	No	Free text region name, e.g. "California".
timezone	Optional[str]	No	IANA timezone string, e.g. "America/Los_Angeles".

Usage Examples

import openai

client = openai.OpenAI()

# Create a response that uses the web search tool
response = client.responses.create(
    model="gpt-4o",
    tools=[{"type": "web_search_preview"}],
    input="What are the latest developments in AI safety?",
)

# Inspect the web search tool in the response
for tool in response.tools:
    if hasattr(tool, "type") and tool.type == "web_search_preview":
        # tool is a WebSearchPreviewTool instance
        print(f"Tool type: {tool.type}")
        print(f"Context size: {tool.search_context_size}")
        if tool.user_location:
            print(f"Location: {tool.user_location.city}, {tool.user_location.country}")

Related Pages

• Environment:Openai_Openai_python_Python_3_9_Plus
• Openai_Openai_python_Web_Search_Tool_Param -- request-side TypedDict counterpart for constructing web search tool parameters