User Location Filter Guide
The user_location
parameter within web_search_options
allows you to refine search results based on the user’s approximate geographic location. This helps provide more contextually relevant information.
You can specify the location using latitude/longitude coordinates, a two-letter ISO country code, or a combination of both coordinates and country code.
Overview
The user_location
filter helps tailor search results by incorporating geographic context. This is particularly useful for queries where location significantly impacts relevance, such as:
- Finding local businesses or services.
- Getting information about regional events or news.
- Understanding location-specific regulations or customs.
To refine search results by location, include the user_location
object within the web_search_options
in your request payload. You can provide coordinates, a country code, or combine them:
Using Latitude/Longitude:
Using Country Code:
Combining Latitude/Longitude and Country Code:
These filters work alongside other search parameters like date range or domain filters.
Examples
1. Refining Results with Latitude and Longitude
This example provides specific coordinates (approximating San Francisco) to get geographically relevant search results.
Request Example
2. Refining Results with Country Code
This example uses a two-letter ISO country code (United States) to provide broader geographic context.
Request Example
3. Combining Coordinates and Country Code
This example provides both specific coordinates (approximating Paris) and the country code (“FR”) for maximum geographic context.
Request Example
Best Practices
Choosing the Right Specificity • Latitude/Longitude: Use for high precision when the exact location is known and relevant (e.g., finding nearby points of interest). • Country Code: Use for broader context when country-level relevance is sufficient (e.g., national news, country-specific regulations). • Combining Fields: Providing both coordinates and country code can offer the most context. The coordinates give precision, while the country code adds broader regional signals (like language or national context) that might influence results.
Data Accuracy • Ensure the provided location data is as accurate as possible. Incorrect data may lead to irrelevant results. • Latitude values must be between -90 and 90. Longitude values must be between -180 and 180. • Country codes should be valid two-letter ISO 3166-1 alpha-2 codes (e.g., “US”, “GB”, “DE”).
Privacy Considerations • Be mindful of user privacy when collecting and transmitting location data. Only use location when necessary and with user consent where applicable.
Client-Side Validation • Consider validating location inputs before sending the request:
- Check latitude/longitude ranges.
- Validate country code format (two uppercase letters).
⸻