add query param (#36)

* add query param

* changed docstring

Author: Stepbus

examples/Businesses.md

@@ -88,21 +88,21 @@ json = {
     'include_total': False,
     'fields': ['name', 'types', 'address', 'state', 'postal_code', 'country', 'website', 'phone', 'rating', 'reviews', 'photo'],
     'filters': {
-        "country_code": "US",
-        "states": [
-            "NY"
+        'country_code': 'US',
+        'states': [
+            'NY'
         ],
-        "cities": [
-            "New York",
-            "Buffalo"
+        'cities': [
+            'New York',
+            'Buffalo'
         ],
-        "types": [
-            "restaurant",
-            "cafe"
+        'types': [
+            'restaurant',
+            'cafe'
         ],
-        "has_website": True,
-        "has_phone": True,
-        "business_statuses": ["operational"],
+        'has_website': True,
+        'has_phone': True,
+        'business_statuses': ['operational'],
     }
 }
 result = client.businesses.search(**json)
@@ -119,4 +119,56 @@ for business in client.businesses.iter_search(
 ):
     # business is a Business dataclass instance
     print(business)
+
+```
+
+---
+
+## 🚀 AI-Powered Natural Language Search
+
+> [!IMPORTANT]
+> **Use plain English to search businesses.**
+>
+> You can now pass a `query` string, and AI will automatically convert it into structured `filters`, `fields`, and other search parameters.
+
+### AI-Powered Search (Plain Text)
+
+```python
+# Describe your request in plain English using the query parameter.
+result = client.businesses.search(
+    query=(
+        'Find restaurants and cafes in California and Illinois with rating 4.2+ and status operational. Return fields name, address, rating and reviews. Limit results to 15.'
+    )
+)
+
+for business in result.items:
+    print(business.name, business.rating)
+```
+
+### Combine JSON + Plain Text (Merge Rules)
+
+When you pass both `filters`/`fields` and `query`:
+
+- `filters` are merged
+- `fields` are merged
+- `limit`, `cursor`, and `include_total` come from plain text first (if present)
+
+```python
+result = client.businesses.search(
+    filters={
+        'country_code': 'US',
+        'states': ['CA'],
+        'types': ['restaurant']
+    },
+    fields=['name', 'phone'],
+    limit=15,
+    query=(
+        'Add cafes too. Return address and reviews. Limit 20. Include total.'
+    ),
+)
+
+# Result behavior:
+# - filters merged (types include restaurant + cafe, plus other JSON filters)
+# - fields merged (name, phone, address, reviews, ...)
+# - limit=20 and include_total=True are taken from plain text
 ```

outscraper/businesses.py

@@ -12,7 +12,7 @@ def __init__(self, client: OutscraperClient) -> None:
         self._client = client
 
     def search(self, *, filters: FiltersLike = None, limit: int = 10, cursor: Optional[str] = None, include_total: bool = False,
-        fields: Optional[list[str]] = None) -> BusinessSearchResult:
+        fields: Optional[list[str]] = None, query: str = '') -> BusinessSearchResult:
         '''
             Retrieve business records with optional enrichment data.
 
@@ -30,6 +30,7 @@ def search(self, *, filters: FiltersLike = None, limit: int = 10, cursor: Option
                     include_total (bool): Whether to include the total count of matching records in the response. This could increase response time.
                         Default: False.
                     fields (list[str] | None): List of fields to include in the response. If not specified, all fields will be returned.
+                    query (str): natural language search.
 
                 Returns:
                         BusinessSearchResult: Page of businesses with pagination info.
@@ -56,6 +57,9 @@ def search(self, *, filters: FiltersLike = None, limit: int = 10, cursor: Option
         if fields:
             payload['fields'] = list(fields)
 
+        if query:
+            payload['query'] = query
+
         response = self._client._request('POST', '/businesses', use_handle_response=False, json=payload)
         data = response.json()
 

setup.py

@@ -8,7 +8,7 @@ def readme():
 
 setup(
     name='outscraper',
-    version='6.0.1',
+    version='6.0.2',
     description='Python bindings for the Outscraper API',
     long_description=readme(),
     classifiers = ['Programming Language :: Python',