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 either using latitude/longitude coordinates and a two-letter ISO country code, or only a two-letter ISO country code. For supported country codes, please refer to the list here.

Latitude and longitude must be provided alongside the country parameter, they cannot be provided on their own.

​
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:

"web_search_options": {
  "user_location": {
    "country":"US",
    "latitude": 37.7749,
    "longitude": -122.4194
  }
}

Using Country Code:

"web_search_options": {
  "user_location": {
    "country": "US"
  }
}

Combining Latitude/Longitude and Country Code:

"web_search_options": {
  "user_location": {
    "latitude": 48.8566, 
    "longitude": 2.3522,
    "country": "FR" // Example: Paris, France
  }
}

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

curl --location 'https://api.perplexity.ai/chat/completions' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "sonar-pro",
    "messages": [
      {"role": "system", "content": "You are a helpful local guide."},
      {"role": "user", "content": "What are some good coffee shops nearby?"}
    ],
    "web_search_options": {
      "user_location": {
        "latitude": 37.7749,
        "longitude": -122.4194
      }
    }
}'

2. Refining Results with Country Code

This example uses a two-letter ISO country code (United States) to provide broader geographic context.

Request Example

curl --location 'https://api.perplexity.ai/chat/completions' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "sonar-pro",
    "messages": [
      {"role": "system", "content": "You are an expert on international news."},
      {"role": "user", "content": "Summarize today's political news."}
    ],
    "web_search_options": {
      "user_location": {
        "country": "US"
      }
    }
}'

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

curl --location 'https://api.perplexity.ai/chat/completions' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "sonar-pro",
    "messages": [
      {"role": "system", "content": "You are an expert on French news and events."},
      {"role": "user", "content": "What major events are happening in the capital this week?"}
    ],
    "web_search_options": {
      "user_location": {
        "latitude": 48.8566, 
        "longitude": 2.3522,
        "country": "FR"
      }
    }
}'

​
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).

⸻