Implementation:Openai Openai python Web Search Tool Param

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

Overview

TypedDict parameter type for constructing web search tool configurations in requests to the OpenAI Responses API.

Description

WebSearchToolParam is a TypedDict that defines the shape of the web search tool dictionary passed in the tools list when creating a response. It includes a required type field (one of "web_search" or "web_search_2025_08_26"), an optional filters object for restricting search to specific domains, a search_context_size setting that controls how much context window space the search consumes, and an optional UserLocation to localize results geographically. The nested Filters TypedDict supports an allowed_domains list, while UserLocation provides optional fields for city, country, region, timezone, and a type literal fixed to "approximate".

Usage

Import WebSearchToolParam when you need to type-annotate the web search tool dictionaries you pass to client.responses.create(). It is the request-side counterpart to WebSearchPreviewTool (the response-side Pydantic model).

Code Reference

Source Location

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

Signature

class Filters(TypedDict, total=False):
    """Filters for the search."""
    allowed_domains: Optional[SequenceNotStr[str]]

class UserLocation(TypedDict, total=False):
    """The approximate location of the user."""
    city: Optional[str]
    country: Optional[str]
    region: Optional[str]
    timezone: Optional[str]
    type: Literal["approximate"]

class WebSearchToolParam(TypedDict, total=False):
    """Search the Internet for sources related to the prompt."""
    type: Required[Literal["web_search", "web_search_2025_08_26"]]
    filters: Optional[Filters]
    search_context_size: Literal["low", "medium", "high"]
    user_location: Optional[UserLocation]

Import

from openai.types.responses import WebSearchToolParam

I/O Contract

WebSearchToolParam Fields

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

Filters Fields

Name	Type	Required	Description
allowed_domains	Optional[SequenceNotStr[str]]	No	List of allowed domains for the search. Subdomains of listed domains are also allowed. If omitted, all domains are permitted. Example: ["pubmed.ncbi.nlm.nih.gov"].

UserLocation Fields

Name	Type	Required	Description
type	Literal["approximate"]	No	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

from openai import OpenAI
from openai.types.responses import WebSearchToolParam

client = OpenAI()

# Basic web search tool
tool: WebSearchToolParam = {"type": "web_search"}

# Web search with domain filters and user location
tool_with_options: WebSearchToolParam = {
    "type": "web_search",
    "search_context_size": "high",
    "filters": {
        "allowed_domains": ["arxiv.org", "pubmed.ncbi.nlm.nih.gov"],
    },
    "user_location": {
        "type": "approximate",
        "city": "San Francisco",
        "region": "California",
        "country": "US",
        "timezone": "America/Los_Angeles",
    },
}

response = client.responses.create(
    model="gpt-4o",
    tools=[tool_with_options],
    input="What are the latest papers on transformer architectures?",
)
print(response.output_text)

Related Pages

• Environment:Openai_Openai_python_Python_3_9_Plus
• Openai_Openai_python_Web_Search_Preview_Tool -- response-side Pydantic model counterpart returned by the API