diff --git a/README.md b/README.md index d8619c9..d4891e6 100644 --- a/README.md +++ b/README.md @@ -41,6 +41,31 @@ for result in search.results: print(f"{result.title}: {result.url}") ``` +### Search with country filtering + +You can restrict search results to specific countries using the `country` parameter: + +```python +# Search for results from the United States +search_us = client.search.create( + query="latest tech news", + country="US", # ISO 3166-1 alpha-2 country code + max_results=5 +) + +# Search for results from the United Kingdom +search_uk = client.search.create( + query="weather forecast", + country="GB", # UK country code + max_results=5 +) + +for result in search_us.results: + print(f"{result.title}: {result.url}") +``` + +The `country` parameter accepts ISO 3166-1 alpha-2 country codes (e.g., "US", "GB", "CA", "DE", "FR", "JP", "AU", "IN"). + ## Chat Completions The full API of this library can be found in [api.md](api.md). @@ -509,4 +534,4 @@ Python 3.8 or higher. ## Contributing -See [the contributing documentation](./CONTRIBUTING.md). +See [the contributing documentation](./CONTRIBUTING.md). \ No newline at end of file diff --git a/examples/search_with_country.py b/examples/search_with_country.py new file mode 100644 index 0000000..87758de --- /dev/null +++ b/examples/search_with_country.py @@ -0,0 +1,115 @@ +#!/usr/bin/env python3 +""" +Example demonstrating the use of the country parameter in Perplexity search API. + +This example shows how to use the newly added country parameter to restrict +search results to specific countries. + +Before running this example: +1. Set your PERPLEXITY_API_KEY environment variable +2. Install the perplexity package: pip install perplexityai + +Usage: + python examples/search_with_country.py +""" + +import os +from perplexity import Perplexity + + +def main(): + # Initialize the Perplexity client + client = Perplexity( + api_key=os.environ.get("PERPLEXITY_API_KEY") + ) + + # Example 1: Search with US country filter + print("πŸ‡ΊπŸ‡Έ Searching for 'latest tech news' with country='US'") + print("-" * 60) + + try: + search_us = client.search.create( + query="latest tech news", + country="US", # This is the new parameter! + max_results=3 + ) + + for i, result in enumerate(search_us.results, 1): + print(f"{i}. {result.title}") + print(f" URL: {result.url}") + print() + + except Exception as e: + print(f"Error: {e}") + print("Note: You need a valid PERPLEXITY_API_KEY to run this example.") + return + + print("\n" + "=" * 60 + "\n") + + # Example 2: Search with UK country filter + print("πŸ‡¬πŸ‡§ Searching for 'weather forecast' with country='GB'") + print("-" * 60) + + try: + search_uk = client.search.create( + query="weather forecast", + country="GB", # UK country code + max_results=3 + ) + + for i, result in enumerate(search_uk.results, 1): + print(f"{i}. {result.title}") + print(f" URL: {result.url}") + print() + + except Exception as e: + print(f"Error: {e}") + + print("\n" + "=" * 60 + "\n") + + # Example 3: Async usage with country parameter + print("🌍 Demonstrating async usage with country parameter") + print("-" * 60) + + import asyncio + from perplexity import AsyncPerplexity + + async def async_search_example(): + async_client = AsyncPerplexity( + api_key=os.environ.get("PERPLEXITY_API_KEY") + ) + + try: + search = await async_client.search.create( + query="popular restaurants", + country="CA", # Canada + max_results=2 + ) + + print("πŸ‡¨πŸ‡¦ Canadian restaurant search results:") + for i, result in enumerate(search.results, 1): + print(f"{i}. {result.title}") + print(f" URL: {result.url}") + print() + + except Exception as e: + print(f"Async error: {e}") + + # Run the async example + asyncio.run(async_search_example()) + + print("βœ… Country parameter examples completed!") + print("\nNote: The country parameter accepts ISO 3166-1 alpha-2 country codes:") + print("- US (United States)") + print("- GB (United Kingdom)") + print("- CA (Canada)") + print("- DE (Germany)") + print("- FR (France)") + print("- JP (Japan)") + print("- AU (Australia)") + print("- IN (India)") + print("- And many more...") + + +if __name__ == "__main__": + main() \ No newline at end of file diff --git a/src/perplexity/resources/search.py b/src/perplexity/resources/search.py index cf7250f..777dd0a 100644 --- a/src/perplexity/resources/search.py +++ b/src/perplexity/resources/search.py @@ -48,6 +48,7 @@ def create( self, *, query: Union[str, SequenceNotStr[str]], + country: Optional[str] | Omit = omit, display_server_time: bool | Omit = omit, max_results: int | Omit = omit, max_tokens: int | Omit = omit, @@ -68,6 +69,8 @@ def create( Search the web and retrieve relevant web page contents. Args: + country: Country code to restrict search results to a specific country (e.g., "US", "GB", "CA") + extra_headers: Send extra headers extra_query: Add additional query parameters to the request @@ -81,6 +84,7 @@ def create( body=maybe_transform( { "query": query, + "country": country, "display_server_time": display_server_time, "max_results": max_results, "max_tokens": max_tokens, @@ -124,6 +128,7 @@ async def create( self, *, query: Union[str, SequenceNotStr[str]], + country: Optional[str] | Omit = omit, display_server_time: bool | Omit = omit, max_results: int | Omit = omit, max_tokens: int | Omit = omit, @@ -144,6 +149,8 @@ async def create( Search the web and retrieve relevant web page contents. Args: + country: Country code to restrict search results to a specific country (e.g., "US", "GB", "CA") + extra_headers: Send extra headers extra_query: Add additional query parameters to the request @@ -157,6 +164,7 @@ async def create( body=await async_maybe_transform( { "query": query, + "country": country, "display_server_time": display_server_time, "max_results": max_results, "max_tokens": max_tokens, @@ -209,4 +217,4 @@ def __init__(self, search: AsyncSearchResource) -> None: self.create = async_to_streamed_response_wrapper( search.create, - ) + ) \ No newline at end of file diff --git a/src/perplexity/types/search_create_params.py b/src/perplexity/types/search_create_params.py index e620b0e..ab47c81 100644 --- a/src/perplexity/types/search_create_params.py +++ b/src/perplexity/types/search_create_params.py @@ -13,6 +13,8 @@ class SearchCreateParams(TypedDict, total=False): query: Required[Union[str, SequenceNotStr[str]]] + country: Optional[str] + display_server_time: bool max_results: int @@ -29,4 +31,4 @@ class SearchCreateParams(TypedDict, total=False): search_mode: Optional[Literal["web", "academic", "sec"]] - search_recency_filter: Optional[Literal["hour", "day", "week", "month", "year"]] + search_recency_filter: Optional[Literal["hour", "day", "week", "month", "year"]] \ No newline at end of file