Add request timeout (#24)

* feat: Introduce request timeout handling and allow passing requests-specific arguments to API calls, along with updating documentation and removing the README template.

* Set version to 0.1.6 and add support for request timeouts

* update changelog history

* fix broken link

Author: jvmvik

HISTORY.md

@@ -1,6 +1,12 @@
 Release History
 ===============
 
+0.1.6 (2026-02-16)
+------------------
+
+- Add support for request timeouts.
+- Add status and error codes support - https://serpapi.com/api-status-and-error-codes
+
 0.1.5 (2023-11-01)
 ------------------
 

README.md

@@ -3,7 +3,7 @@
 <h1 align="center">SerpApi Python Library & Package</h1>
   <img src="https://user-images.githubusercontent.com/78694043/233921372-bb57c347-9005-4b59-8f09-993698a87eb6.svg" width="600" alt="serpapi python library logo">
 
-  <a href="https://badge.fury.io/py/serpapi-python">![Package](https://badge.fury.io/py/serpapi.svg)</a>
+  <a href="https://pypi.org/project/serpapi">![Package](https://badge.fury.io/py/serpapi.svg)</a>
 
   [![serpapi-python](https://github.com/serpapi/serpapi-python/actions/workflows/ci.yml/badge.svg)](https://github.com/serpapi/serpapi-python/actions/workflows/ci.yml)
 </div>
@@ -52,12 +52,13 @@ The [SerpApi.com API Documentation](https://serpapi.com/search-api) contains a l
 
 ### Error handling
 
-Unsuccessful requests raise `serpapi.HTTPError` exception. The returned status code will reflect the sort of error that occurred, please refer to [Status and Error Codes Documentation](https://serpapi.com/api-status-and-error-codes) for more details.
+Unsuccessful requests raise `serpapi.HTTPError` or `serpapi.TimeoutError` exceptions. The returned status code will reflect the sort of error that occurred, please refer to [Status and Error Codes Documentation](https://serpapi.com/api-status-and-error-codes) for more details.
 
 ```python
 import serpapi
 
-client = serpapi.Client(api_key=os.getenv("API_KEY"))
+# A default timeout can be set here.
+client = serpapi.Client(api_key=os.getenv("API_KEY"), timeout=10)
 
 try:
     results = client.search({
@@ -71,12 +72,17 @@ except serpapi.HTTPError as e:
         pass
     elif e.status_code == 429: # Exceeds the hourly throughput limit OR account run out of searches
         pass
+except serpapi.TimeoutError as e:
+    # Handle timeout
+    print(f"The request timed out: {e}")
 ```
 
 ## Documentation
 
 Documentation is [available on Read the Docs](https://serpapi-python.readthedocs.io/en/latest/).
 
+Change history is [available on GitHub](https://github.com/serpapi/serpapi-python/blob/master/HISTORY.md).
+
 ## Basic Examples in Python
 
 ### Search Bing

README.md.erb

@@ -1 +1 @@
-__version__ = "0.1.5"
+__version__ = "0.1.6"

serpapi/__version__.py

@@ -25,6 +25,9 @@ class Client(HTTPClient):
 
     DASHBOARD_URL = "https://serpapi.com/dashboard"
 
+    def __init__(self, *, api_key=None, timeout=None):
+        super().__init__(api_key=api_key, timeout=timeout)
+
     def __repr__(self):
         return "<SerpApi Client>"
 
@@ -60,10 +63,16 @@ def search(self, params: dict = None, **kwargs):
         if params is None:
             params = {}
 
+        # These are arguments that should be passed to the underlying requests.request call.
+        request_kwargs = {}
+        for key in ["timeout", "proxies", "verify", "stream", "cert"]:
+            if key in kwargs:
+                request_kwargs[key] = kwargs.pop(key)
+
         if kwargs:
             params.update(kwargs)
 
-        r = self.request("GET", "/search", params=params)
+        r = self.request("GET", "/search", params=params, **request_kwargs)
 
         return SerpResults.from_http_response(r, client=self)
 
@@ -80,6 +89,12 @@ def search_archive(self, params: dict = None, **kwargs):
         if params is None:
             params = {}
 
+        # These are arguments that should be passed to the underlying requests.request call.
+        request_kwargs = {}
+        for key in ["timeout", "proxies", "verify", "stream", "cert"]:
+            if key in kwargs:
+                request_kwargs[key] = kwargs.pop(key)
+
         if kwargs:
             params.update(kwargs)
 
@@ -90,7 +105,7 @@ def search_archive(self, params: dict = None, **kwargs):
                 f"Please provide 'search_id', found here: { self.DASHBOARD_URL }"
             )
 
-        r = self.request("GET", f"/searches/{ search_id }", params=params)
+        r = self.request("GET", f"/searches/{ search_id }", params=params, **request_kwargs)
         return SerpResults.from_http_response(r, client=self)
 
     def locations(self, params: dict = None, **kwargs):
@@ -106,6 +121,12 @@ def locations(self, params: dict = None, **kwargs):
         if params is None:
             params = {}
 
+        # These are arguments that should be passed to the underlying requests.request call.
+        request_kwargs = {}
+        for key in ["timeout", "proxies", "verify", "stream", "cert"]:
+            if key in kwargs:
+                request_kwargs[key] = kwargs.pop(key)
+
         if kwargs:
             params.update(kwargs)
 
@@ -114,6 +135,7 @@ def locations(self, params: dict = None, **kwargs):
             "/locations.json",
             params=params,
             assert_200=True,
+            **request_kwargs,
         )
         return r.json()
 
@@ -129,10 +151,16 @@ def account(self, params: dict = None, **kwargs):
         if params is None:
             params = {}
 
+        # These are arguments that should be passed to the underlying requests.request call.
+        request_kwargs = {}
+        for key in ["timeout", "proxies", "verify", "stream", "cert"]:
+            if key in kwargs:
+                request_kwargs[key] = kwargs.pop(key)
+
         if kwargs:
             params.update(kwargs)
 
-        r = self.request("GET", "/account.json", params=params, assert_200=True)
+        r = self.request("GET", "/account.json", params=params, assert_200=True, **request_kwargs)
         return r.json()
 
 

serpapi/core.py

@@ -43,3 +43,9 @@ class HTTPConnectionError(HTTPError, requests.exceptions.ConnectionError, SerpAp
     """Connection Error."""
 
     pass
+
+
+class TimeoutError(requests.exceptions.Timeout, SerpApiError):
+    """Timeout Error."""
+
+    pass

serpapi/exceptions.py

@@ -3,6 +3,7 @@
 from .exceptions import (
     HTTPError,
     HTTPConnectionError,
+    TimeoutError,
 )
 from .__version__ import __version__
 
@@ -13,10 +14,11 @@ class HTTPClient:
     BASE_DOMAIN = "https://serpapi.com"
     USER_AGENT = f"serpapi-python, v{__version__}"
 
-    def __init__(self, *, api_key=None):
+    def __init__(self, *, api_key=None, timeout=None):
         # Used to authenticate requests.
         # TODO: do we want to support the environment variable? Seems like a security risk.
         self.api_key = api_key
+        self.timeout = timeout
         self.session = requests.Session()
 
     def request(self, method, path, params, *, assert_200=True, **kwargs):
@@ -34,12 +36,18 @@ def request(self, method, path, params, *, assert_200=True, **kwargs):
         try:
             headers = {"User-Agent": self.USER_AGENT}
 
+            # Use the default timeout if one was provided to the client.
+            if self.timeout and "timeout" not in kwargs:
+                kwargs["timeout"] = self.timeout
+
             r = self.session.request(
                 method=method, url=url, params=params, headers=headers, **kwargs
             )
 
         except requests.exceptions.ConnectionError as e:
             raise HTTPConnectionError(e)
+        except requests.exceptions.Timeout as e:
+            raise TimeoutError(e)
 
         # Raise an exception if the status code is not 200.
         if assert_200: