How can an API search test specify a city and timezone?

Definition: An OpenAI web search request can carry an approximate user location in the user_location object of the web_search tool. The object can include a city, region, country and IANA timezone so a search test supplies geographic context without asserting a precise position.

Key facts

• OpenAI's web search guide says geographic refinement accepts country, city, region and/or timezone.
• The guide defines city and region as free text strings, while country is a two-letter ISO country code and timezone is an IANA timezone.
• The Responses API reference defines user_location as optional and says an omitted or null value defaults to the United States.
• The reference says type is always approximate; the location object therefore describes test context rather than a precise device position.
• OpenAI's guide states that user location is unsupported for deep research models using web search.

What should the request contain?

The user_location object belongs inside the web search tool configuration. A compact test payload that follows the documented field types is:

{
  "type": "web_search",
  "user_location": {
    "type": "approximate",
    "city": "Minneapolis",
    "timezone": "America/Chicago"
  }
}

The guide's field description permits the city and timezone to be supplied without a country or region. Its examples use Minneapolis for a city and America/Chicago for a timezone. The API reference describes the fields as optional strings or null, and gives San Francisco as a city example and America/Los_Angeles as a timezone example.

How should a test represent geographic context?

An API test uses a free text city name in city. A free text regional name in region supplies a broader administrative context when needed. The country value uses a two-letter ISO country code such as US, while the timezone uses an IANA identifier such as America/Chicago, according to OpenAI's web search documentation.

The API reference describes user_location as the approximate location of the user and says that relevant location fields localize results. It also documents a default: when the object is omitted or null, the API uses the United States. A test that wants an explicitly unspecified approximate location can pass {"type": "approximate"} without location fields, which the reference gives as the way to avoid that fallback.

What does this change in a search test?

The location object changes the geographic context supplied to web search. It does not turn the request into a precise geolocation signal, because the documented type is approximate and the city and region values are free text.

The request path matters as well. OpenAI's guide says the current web_search tool is configured in the Responses API and that the model can choose whether to search based on the input prompt. The same guide says the earlier web_search_preview tool remains available for legacy integrations but lacks newer controls. User location is not supported for deep research models using web search, so that model path is outside this test design.

How can the result be checked?

A controlled comparison records the exact location object with the request and changes one field at a time. The API reference identifies the object fields as city, country, region, timezone and type, and the guide supplies the accepted formats and examples. OpenAI's web search output documentation also states that a response using the tool contains a web_search_call output item and a message containing URL annotations for cited sources.

The documentation does not specify a precision radius, geocoding process, or precedence rule when city, region, country and timezone describe different contexts. Those points remain open when interpreting a controlled comparison.

Related terms

• ChatGPT search
• ChatGPT deep research
• Interface language and search language

FAQ

Can a test send only a city and timezone?

Yes. OpenAI documents the location fields as optional and the guide describes the fields as usable in combination with country, city, region and/or timezone. The object still needs "type": "approximate".

What happens when user_location is omitted?

The Responses API reference says an omitted or null user_location defaults to the United States. To avoid that fallback, pass {"type": "approximate"} without location fields.

Can deep research use this location object?

No. OpenAI's web search guide states that user location is not supported for deep research models using web search.

Sources

1. OpenAI, "Web search", undated
2. OpenAI, "Create a model response", undated

---

Check how a page reads to answer engines. Open the GEO score analyzer