feat: add time_range parameter to SearchScraper

Adds optional time_range filter to SearchScraper for filtering search
results by recency. Supports the following time ranges:
- past_hour
- past_24_hours
- past_week
- past_month
- past_year

This allows users to filter search results to only recent content.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: VinciGit00

scrapegraph-py/scrapegraph_py/async_client.py

@@ -61,6 +61,7 @@
 from scrapegraph_py.models.searchscraper import (
     GetSearchScraperRequest,
     SearchScraperRequest,
+    TimeRange,
 )
 from scrapegraph_py.models.sitemap import SitemapRequest, SitemapResponse
 from scrapegraph_py.models.smartscraper import (
@@ -783,6 +784,7 @@ async def searchscraper(
         extraction_mode: bool = True,
         stealth: bool = False,
         location_geo_code: Optional[str] = None,
+        time_range: Optional[TimeRange] = None,
         return_toon: bool = False,
     ):
         """Send a searchscraper request
@@ -799,6 +801,7 @@ async def searchscraper(
                            AI extraction costs 10 credits per page, markdown conversion costs 2 credits per page.
             stealth: Enable stealth mode to avoid bot detection
             location_geo_code: Optional geo code of the location to search in (e.g., "us")
+            time_range: Optional time range filter for search results (e.g., TimeRange.PAST_WEEK)
             return_toon: If True, return response in TOON format (reduces token usage by 30-60%)
         """
         logger.info("🔍 Starting searchscraper request")
@@ -811,6 +814,8 @@ async def searchscraper(
             logger.debug("🥷 Stealth mode enabled")
         if location_geo_code:
             logger.debug(f"🌍 Location geo code: {location_geo_code}")
+        if time_range:
+            logger.debug(f"📅 Time range: {time_range.value}")
         if return_toon:
             logger.debug("🎨 TOON format output enabled")
 
@@ -822,6 +827,7 @@ async def searchscraper(
             extraction_mode=extraction_mode,
             stealth=stealth,
             location_geo_code=location_geo_code,
+            time_range=time_range,
         )
         logger.debug("✅ Request validation passed")
 

scrapegraph-py/scrapegraph_py/client.py

@@ -54,6 +54,7 @@
 from scrapegraph_py.models.searchscraper import (
     GetSearchScraperRequest,
     SearchScraperRequest,
+    TimeRange,
 )
 from scrapegraph_py.models.sitemap import SitemapRequest, SitemapResponse
 from scrapegraph_py.models.smartscraper import (
@@ -790,9 +791,10 @@ def searchscraper(
         headers: Optional[dict[str, str]] = None,
         output_schema: Optional[BaseModel] = None,
         extraction_mode: bool = True,
-        mock: bool=False,
-        stealth: bool=False,
+        mock: bool = False,
+        stealth: bool = False,
         location_geo_code: Optional[str] = None,
+        time_range: Optional[TimeRange] = None,
         return_toon: bool = False,
     ):
         """Send a searchscraper request
@@ -810,6 +812,7 @@ def searchscraper(
             mock: Enable mock mode for testing
             stealth: Enable stealth mode to avoid bot detection
             location_geo_code: Optional geo code of the location to search in (e.g., "us")
+            time_range: Optional time range filter for search results (e.g., TimeRange.PAST_WEEK)
             return_toon: If True, return response in TOON format (reduces token usage by 30-60%)
         """
         logger.info("🔍 Starting searchscraper request")
@@ -822,6 +825,8 @@ def searchscraper(
             logger.debug("🥷 Stealth mode enabled")
         if location_geo_code:
             logger.debug(f"🌍 Location geo code: {location_geo_code}")
+        if time_range:
+            logger.debug(f"📅 Time range: {time_range.value}")
         if return_toon:
             logger.debug("🎨 TOON format output enabled")
 
@@ -834,6 +839,7 @@ def searchscraper(
             mock=mock,
             stealth=stealth,
             location_geo_code=location_geo_code,
+            time_range=time_range,
         )
         logger.debug("✅ Request validation passed")
 

scrapegraph-py/scrapegraph_py/models/__init__.py

@@ -29,7 +29,7 @@
 from .feedback import FeedbackRequest
 from .scrape import GetScrapeRequest, ScrapeRequest
 from .markdownify import GetMarkdownifyRequest, MarkdownifyRequest
-from .searchscraper import GetSearchScraperRequest, SearchScraperRequest
+from .searchscraper import GetSearchScraperRequest, SearchScraperRequest, TimeRange
 from .sitemap import SitemapRequest, SitemapResponse
 from .smartscraper import GetSmartScraperRequest, SmartScraperRequest
 from .schema import GenerateSchemaRequest, GetSchemaStatusRequest, SchemaGenerationResponse
@@ -46,6 +46,7 @@
     "MarkdownifyRequest",
     "GetSearchScraperRequest",
     "SearchScraperRequest",
+    "TimeRange",
     "SitemapRequest",
     "SitemapResponse",
     "GetSmartScraperRequest",

scrapegraph-py/scrapegraph_py/models/searchscraper.py

@@ -12,12 +12,34 @@
 - Supports both AI extraction and markdown conversion modes
 """
 
+from enum import Enum
 from typing import Optional, Type
 from uuid import UUID
 
 from pydantic import BaseModel, Field, model_validator
 
 
+class TimeRange(str, Enum):
+    """Time range filter for search results.
+
+    Controls how recent the search results should be. This is useful for
+    finding recent news, updates, or time-sensitive information.
+
+    Values:
+        PAST_HOUR: Results from the past hour
+        PAST_24_HOURS: Results from the past 24 hours
+        PAST_WEEK: Results from the past week
+        PAST_MONTH: Results from the past month
+        PAST_YEAR: Results from the past year
+    """
+
+    PAST_HOUR = "past_hour"
+    PAST_24_HOURS = "past_24_hours"
+    PAST_WEEK = "past_week"
+    PAST_MONTH = "past_month"
+    PAST_YEAR = "past_year"
+
+
 class SearchScraperRequest(BaseModel):
     """
     Request model for the SearchScraper endpoint.
@@ -34,6 +56,7 @@ class SearchScraperRequest(BaseModel):
         mock: Whether to use mock mode for testing
         render_heavy_js: Whether to render heavy JavaScript
         location_geo_code: Optional geo code for location-based search (e.g., "us")
+        time_range: Optional time range filter for search results
 
     Example:
         >>> request = SearchScraperRequest(
@@ -74,6 +97,17 @@ class SearchScraperRequest(BaseModel):
         description="The geo code of the location to search in",
         example="us",
     )
+    time_range: Optional[TimeRange] = Field(
+        None,
+        description="The date range to filter search results",
+        examples=[
+            TimeRange.PAST_HOUR,
+            TimeRange.PAST_24_HOURS,
+            TimeRange.PAST_WEEK,
+            TimeRange.PAST_MONTH,
+            TimeRange.PAST_YEAR,
+        ],
+    )
 
     @model_validator(mode="after")
     def validate_user_prompt(self) -> "SearchScraperRequest":