Overview
The Search API supports a variety of filtering options to help you get the most relevant results. Combine multiple filters to create precise searches tailored to your specific needs.
Domain Filtering
The search_domain_filter parameter allows you to limit search results to specific domains/URLs for focused research:
from perplexity import Perplexity
client = Perplexity()
search = client.search.create(
query="climate change research",
search_domain_filter=[
"science.org",
"pnas.org",
"cell.com"
],
max_results=10
)
for result in search.results:
print(f"{result.title}: {result.url}")
print(f"Published: {result.date}")
print("---")
You can add a maximum of 20 domains or URLs to the search_domain_filter list.
Recency Filter
Use predefined time periods for quick filtering:
from perplexity import Perplexity
client = Perplexity()
search = client.search.create(
query="latest AI developments",
search_recency_filter="week"
)
for result in search.results:
print(f"{result.title}: {result.url}")
print(f"Published: {result.date}")
print("---")
Available Recency Options
| Value | Description |
|---|
"day" | Results from the past 24 hours |
"week" | Results from the past 7 days |
"month" | Results from the past 30 days |
"year" | Results from the past 365 days |
Date Range Filtering
Control the time range of your search results using various date filtering options. You can filter by publication date or last updated date to find the most relevant and current information.
Publication Date Filters
Filter results based on when content was originally published:
from perplexity import Perplexity
client = Perplexity()
search = client.search.create(
query="quantum computing breakthroughs",
search_after_date_filter="01/01/2024",
search_before_date_filter="12/31/2024"
)
for result in search.results:
print(f"{result.title}: {result.url}")
print(f"Published: {result.date}")
print(f"Last updated: {result.last_updated}")
print("---")
Last Updated Filters
Filter results based on when pages were last modified:
from perplexity import Perplexity
client = Perplexity()
search = client.search.create(
query="AI safety best practices",
last_updated_after_filter="2025-01-01T00:00:00Z",
last_updated_before_filter="2025-06-30T23:59:59Z"
)
for result in search.results:
print(f"{result.title}: {result.url}")
print(f"Published: {result.date}")
print(f"Last updated: {result.last_updated}")
print("---")
Date Filter Parameters
| Parameter | Type | Description | Format |
|---|
search_recency_filter | string | Filter results by how recently they were published | "day", "week", "month", "year" |
search_before_date_filter | string | Results published before this date | "MM/DD/YYYY" |
search_after_date_filter | string | Results published after this date | "MM/DD/YYYY" |
last_updated_before_filter | string | Pages updated before this date | "MM/DD/YYYY" |
last_updated_after_filter | string | Pages updated after this date | "MM/DD/YYYY" |
You cannot combine search_recency_filter with any other date filter parameters in a single request. Use either recency filtering or specific date range filtering, but not both.
Academic Search
Access scholarly articles and research papers for academic purposes:
from perplexity import Perplexity
client = Perplexity()
search = client.search.create(
query="machine learning algorithms",
search_mode="academic",
max_results=10
)
for result in search.results:
print(f"{result.title}")
print(f"Journal/Source: {result.snippet}")
print(f"URL: {result.url}")
print("---")
Academic search mode prioritizes scholarly articles, research papers, and peer-reviewed content from academic institutions and journals.
Location-Based Search
Get geographically relevant results by specifying user location:
from perplexity import Perplexity
client = Perplexity()
# Using coordinates
search = client.search.create(
query="local restaurants",
user_location_filter={
"latitude": 37.7749,
"longitude": -122.4194,
"radius": 10 # km
},
max_results=10
)
# Using location string
city_search = client.search.create(
query="tech events",
user_location_filter="San Francisco, CA",
max_results=10
)
for result in search.results:
print(f"{result.title}: {result.url}")
print(f"Snippet: {result.snippet}")
print("---")
Location Filter Options
| Type | Format | Description |
|---|
| Coordinates | {"latitude": float, "longitude": float, "radius": int} | Precise geographic location with radius in kilometers |
| Location String | "City, State" or "City, Country" | Human-readable location description |
Advanced Search Configuration
Combine multiple filters for precise, targeted results:
from perplexity import Perplexity
client = Perplexity()
# Complex search with multiple filters
search = client.search.create(
query="renewable energy research",
max_results=15,
search_mode="web",
search_recency_filter="month",
search_domain_filter=[
"energy.gov",
"iea.org",
"irena.org",
"nature.com",
"science.org"
],
return_images=True,
return_snippets=True,
user_location_filter="United States"
)
# Process results with metadata
for result in search.results:
print(f"Title: {result.title}")
print(f"URL: {result.url}")
print(f"Date: {result.date}")
print(f"Snippet: {result.snippet}")
if hasattr(result, 'images') and result.images:
print(f"Images: {len(result.images)} found")
print("---")
Filter Combinations
Recommended Filter Patterns
Academic Research
Combine academic mode with domain filtering for scholarly research.search = client.search.create(
query="climate change impacts",
search_mode="academic",
search_domain_filter=["pnas.org", "nature.com", "science.org"],
search_after_date_filter="01/01/2023"
)
Current News
Use recency filtering with trusted news domains.search = client.search.create(
query="tech industry updates",
search_recency_filter="week",
search_domain_filter=["reuters.com", "bloomberg.com", "techcrunch.com"]
)
Local Information
Combine location filtering with relevant queries.search = client.search.create(
query="startup events",
user_location_filter="San Francisco, CA",
search_recency_filter="month"
)
Error Handling
Handle search-specific errors gracefully to build robust applications:
from perplexity import Perplexity, BadRequestError, RateLimitError, APIStatusError
client = Perplexity()
try:
search = client.search.create(
query="", # Empty query will cause error
max_results=5
)
except BadRequestError as e:
print(f"Invalid search parameters: {e}")
except RateLimitError as e:
print("Search rate limit exceeded - please wait before retrying")
except APIStatusError as e:
print(f"Search API error {e.status_code}: {e}")
except Exception as e:
print(f"Unexpected error: {e}")
