feat: return raw JSON from high-level client

Anonymous Committer · Anonymous Committer · commit d220ca7f050a · 2026-03-22T18:44:48.000+08:00
diff --git a/README.md b/README.md
@@ -38,7 +38,8 @@ with Client(api_key="YOUR_API_KEY") as client:
         location="New York, NY",
         language="en",
     )
-    print(response.organic_results)
+    print(response)
+    print(response["data"])
 ```
 
 ## Promoted High-Level API
@@ -57,17 +58,12 @@ images = client.google.images.search(query="espresso machine")
 shopping = client.google.shopping.search(query="espresso tamper")
 overview = client.google.ai.overview(url="https://example.com/ai-overview")
 
+print(search["data"])
+
 client.close()
 ```
 
-Promoted high-level responses are parsed into Pydantic models:
-
-- `GoogleSearchResponse`
-- `GoogleMapsSearchResponse`
-- `GoogleNewsSearchResponse`
-- `GoogleImagesSearchResponse`
-- `GoogleShoppingSearchResponse`
-- `GoogleAIOverviewResponse`
+Promoted high-level responses are plain Python dictionaries that mirror the API's JSON response envelope. The SDK does not auto-unpack `data`.
 
 ## Configuration
 
diff --git a/justserpapi/__init__.py b/justserpapi/__init__.py
@@ -16,13 +16,6 @@
     "ApiKeyError",
     "ApiAttributeError",
     "ApiException",
-    "GoogleSearchResponse",
-    "GoogleMapsSearchResponse",
-    "GoogleNewsSearchResponse",
-    "GoogleImagesSearchResponse",
-    "GoogleShoppingSearchResponse",
-    "GoogleAIOverviewResponse",
-    "GoogleAutocompleteResponse",
 ]
 
 # import high-level client
@@ -35,12 +28,3 @@
 from justserpapi.exceptions import ApiKeyError as ApiKeyError
 from justserpapi.exceptions import ApiAttributeError as ApiAttributeError
 from justserpapi.exceptions import ApiException as ApiException
-
-# import models into sdk package
-from justserpapi.models import GoogleAIOverviewResponse as GoogleAIOverviewResponse
-from justserpapi.models import GoogleAutocompleteResponse as GoogleAutocompleteResponse
-from justserpapi.models import GoogleImagesSearchResponse as GoogleImagesSearchResponse
-from justserpapi.models import GoogleMapsSearchResponse as GoogleMapsSearchResponse
-from justserpapi.models import GoogleNewsSearchResponse as GoogleNewsSearchResponse
-from justserpapi.models import GoogleSearchResponse as GoogleSearchResponse
-from justserpapi.models import GoogleShoppingSearchResponse as GoogleShoppingSearchResponse
diff --git a/justserpapi/_version.py b/justserpapi/_version.py
@@ -1,3 +1,3 @@
 """Package version."""
 
-__version__ = "2.0.0"
+__version__ = "3.0.0"
diff --git a/justserpapi/client.py b/justserpapi/client.py
@@ -2,26 +2,16 @@
 
 from __future__ import annotations
 
-from typing import Any, Optional, Tuple, Type, TypeVar, Union
+from typing import Any, Dict, Optional, Tuple, Union
 
 from urllib3.util.retry import Retry
 
 from justserpapi.api.google_api_api import GoogleAPIApi
 from justserpapi.api_client import ApiClient
 from justserpapi.configuration import Configuration
-from justserpapi.models.responses import (
-    BasePayloadModel,
-    GoogleAIOverviewResponse,
-    GoogleAutocompleteResponse,
-    GoogleImagesSearchResponse,
-    GoogleMapsSearchResponse,
-    GoogleNewsSearchResponse,
-    GoogleSearchResponse,
-    GoogleShoppingSearchResponse,
-)
 
 TimeoutValue = Optional[Union[float, Tuple[float, float]]]
-T = TypeVar("T", bound=BasePayloadModel)
+JSONDict = Dict[str, Any]
 
 DEFAULT_HOST = "https://api.justserpapi.com"
 DEFAULT_TIMEOUT: TimeoutValue = 30.0
@@ -52,41 +42,42 @@ def _with_timeout(self, kwargs: dict[str, Any]) -> dict[str, Any]:
             kwargs["_request_timeout"] = self._timeout
         return kwargs
 
-    def _typed_call(self, method_name: str, response_model: Type[T], **kwargs: Any) -> T:
+    def _json_call(self, method_name: str, **kwargs: Any) -> JSONDict:
         payload = getattr(self._api, method_name)(**self._with_timeout(kwargs))
-        if isinstance(payload, response_model):
-            return payload
         if isinstance(payload, dict):
-            return response_model.model_validate(payload)
-        return response_model.model_validate({"payload": payload})
+            return payload
+        raise TypeError(
+            "%s returned %s instead of a JSON object."
+            % (method_name, type(payload).__name__)
+        )
 
 
 class GoogleMapsResource(_GoogleBaseResource):
-    def search(self, *, query: str, **kwargs: Any) -> GoogleMapsSearchResponse:
-        return self._typed_call("maps_search", GoogleMapsSearchResponse, query=query, **kwargs)
+    def search(self, *, query: str, **kwargs: Any) -> JSONDict:
+        return self._json_call("maps_search", query=query, **kwargs)
 
 
 class GoogleNewsResource(_GoogleBaseResource):
-    def search(self, *, query: str, **kwargs: Any) -> GoogleNewsSearchResponse:
-        return self._typed_call("news_search", GoogleNewsSearchResponse, query=query, **kwargs)
+    def search(self, *, query: str, **kwargs: Any) -> JSONDict:
+        return self._json_call("news_search", query=query, **kwargs)
 
 
 class GoogleImagesResource(_GoogleBaseResource):
-    def search(self, *, query: str, **kwargs: Any) -> GoogleImagesSearchResponse:
-        return self._typed_call("images_search", GoogleImagesSearchResponse, query=query, **kwargs)
+    def search(self, *, query: str, **kwargs: Any) -> JSONDict:
+        return self._json_call("images_search", query=query, **kwargs)
 
 
 class GoogleShoppingResource(_GoogleBaseResource):
-    def search(self, *, query: str, **kwargs: Any) -> GoogleShoppingSearchResponse:
-        return self._typed_call("shopping_search", GoogleShoppingSearchResponse, query=query, **kwargs)
+    def search(self, *, query: str, **kwargs: Any) -> JSONDict:
+        return self._json_call("shopping_search", query=query, **kwargs)
 
 
 class GoogleAIResource(_GoogleBaseResource):
-    def overview(self, *, url: str, **kwargs: Any) -> GoogleAIOverviewResponse:
-        return self._typed_call("ai_overview", GoogleAIOverviewResponse, url=url, **kwargs)
+    def overview(self, *, url: str, **kwargs: Any) -> JSONDict:
+        return self._json_call("ai_overview", url=url, **kwargs)
 
-    def mode(self, *, query: str, **kwargs: Any) -> GoogleAIOverviewResponse:
-        return self._typed_call("ai_mode", GoogleAIOverviewResponse, query=query, **kwargs)
+    def mode(self, *, query: str, **kwargs: Any) -> JSONDict:
+        return self._json_call("ai_mode", query=query, **kwargs)
 
 
 class GoogleResource(_GoogleBaseResource):
@@ -101,11 +92,11 @@ def __init__(self, api_client: ApiClient, timeout: TimeoutValue) -> None:
         self.shopping = GoogleShoppingResource(api, timeout)
         self.ai = GoogleAIResource(api, timeout)
 
-    def search(self, *, query: str, **kwargs: Any) -> GoogleSearchResponse:
-        return self._typed_call("search", GoogleSearchResponse, query=query, **kwargs)
+    def search(self, *, query: str, **kwargs: Any) -> JSONDict:
+        return self._json_call("search", query=query, **kwargs)
 
-    def autocomplete(self, *, query: str, **kwargs: Any) -> GoogleAutocompleteResponse:
-        return self._typed_call("autocomplete", GoogleAutocompleteResponse, query=query, **kwargs)
+    def autocomplete(self, *, query: str, **kwargs: Any) -> JSONDict:
+        return self._json_call("autocomplete", query=query, **kwargs)
 
 
 class Client:
diff --git a/overlays/python/README.md.tmpl b/overlays/python/README.md.tmpl
@@ -15,7 +15,8 @@ from {{PACKAGE_NAME}} import Client
 
 with Client(api_key="YOUR_API_KEY", base_url="{{DEFAULT_SERVER_URL}}") as client:
     response = client.google.search(query="coffee shops", language="en")
-    print(response.organic_results)
+    print(response)
+    print(response["data"])
 ```
 
 ## Release contract
diff --git a/overlays/python/justserpapi/__init__.py.tmpl b/overlays/python/justserpapi/__init__.py.tmpl
@@ -15,13 +15,6 @@ __all__ = [
     "ApiKeyError",
     "ApiAttributeError",
     "ApiException",
-    "GoogleSearchResponse",
-    "GoogleMapsSearchResponse",
-    "GoogleNewsSearchResponse",
-    "GoogleImagesSearchResponse",
-    "GoogleShoppingSearchResponse",
-    "GoogleAIOverviewResponse",
-    "GoogleAutocompleteResponse",
 ]
 
 from justserpapi.client import Client as Client
@@ -32,10 +25,3 @@ from justserpapi.exceptions import ApiValueError as ApiValueError
 from justserpapi.exceptions import ApiKeyError as ApiKeyError
 from justserpapi.exceptions import ApiAttributeError as ApiAttributeError
 from justserpapi.exceptions import ApiException as ApiException
-from justserpapi.models import GoogleAIOverviewResponse as GoogleAIOverviewResponse
-from justserpapi.models import GoogleAutocompleteResponse as GoogleAutocompleteResponse
-from justserpapi.models import GoogleImagesSearchResponse as GoogleImagesSearchResponse
-from justserpapi.models import GoogleMapsSearchResponse as GoogleMapsSearchResponse
-from justserpapi.models import GoogleNewsSearchResponse as GoogleNewsSearchResponse
-from justserpapi.models import GoogleSearchResponse as GoogleSearchResponse
-from justserpapi.models import GoogleShoppingSearchResponse as GoogleShoppingSearchResponse
diff --git a/overlays/python/justserpapi/client.py b/overlays/python/justserpapi/client.py
@@ -2,26 +2,16 @@
 
 from __future__ import annotations
 
-from typing import Any, Optional, Tuple, Type, TypeVar, Union
+from typing import Any, Dict, Optional, Tuple, Union
 
 from urllib3.util.retry import Retry
 
 from justserpapi.api.google_api_api import GoogleAPIApi
 from justserpapi.api_client import ApiClient
 from justserpapi.configuration import Configuration
-from justserpapi.models.responses import (
-    BasePayloadModel,
-    GoogleAIOverviewResponse,
-    GoogleAutocompleteResponse,
-    GoogleImagesSearchResponse,
-    GoogleMapsSearchResponse,
-    GoogleNewsSearchResponse,
-    GoogleSearchResponse,
-    GoogleShoppingSearchResponse,
-)
 
 TimeoutValue = Optional[Union[float, Tuple[float, float]]]
-T = TypeVar("T", bound=BasePayloadModel)
+JSONDict = Dict[str, Any]
 
 DEFAULT_HOST = "https://api.justserpapi.com"
 DEFAULT_TIMEOUT: TimeoutValue = 30.0
@@ -52,41 +42,42 @@ def _with_timeout(self, kwargs: dict[str, Any]) -> dict[str, Any]:
             kwargs["_request_timeout"] = self._timeout
         return kwargs
 
-    def _typed_call(self, method_name: str, response_model: Type[T], **kwargs: Any) -> T:
+    def _json_call(self, method_name: str, **kwargs: Any) -> JSONDict:
         payload = getattr(self._api, method_name)(**self._with_timeout(kwargs))
-        if isinstance(payload, response_model):
-            return payload
         if isinstance(payload, dict):
-            return response_model.model_validate(payload)
-        return response_model.model_validate({"payload": payload})
+            return payload
+        raise TypeError(
+            "%s returned %s instead of a JSON object."
+            % (method_name, type(payload).__name__)
+        )
 
 
 class GoogleMapsResource(_GoogleBaseResource):
-    def search(self, *, query: str, **kwargs: Any) -> GoogleMapsSearchResponse:
-        return self._typed_call("maps_search", GoogleMapsSearchResponse, query=query, **kwargs)
+    def search(self, *, query: str, **kwargs: Any) -> JSONDict:
+        return self._json_call("maps_search", query=query, **kwargs)
 
 
 class GoogleNewsResource(_GoogleBaseResource):
-    def search(self, *, query: str, **kwargs: Any) -> GoogleNewsSearchResponse:
-        return self._typed_call("news_search", GoogleNewsSearchResponse, query=query, **kwargs)
+    def search(self, *, query: str, **kwargs: Any) -> JSONDict:
+        return self._json_call("news_search", query=query, **kwargs)
 
 
 class GoogleImagesResource(_GoogleBaseResource):
-    def search(self, *, query: str, **kwargs: Any) -> GoogleImagesSearchResponse:
-        return self._typed_call("images_search", GoogleImagesSearchResponse, query=query, **kwargs)
+    def search(self, *, query: str, **kwargs: Any) -> JSONDict:
+        return self._json_call("images_search", query=query, **kwargs)
 
 
 class GoogleShoppingResource(_GoogleBaseResource):
-    def search(self, *, query: str, **kwargs: Any) -> GoogleShoppingSearchResponse:
-        return self._typed_call("shopping_search", GoogleShoppingSearchResponse, query=query, **kwargs)
+    def search(self, *, query: str, **kwargs: Any) -> JSONDict:
+        return self._json_call("shopping_search", query=query, **kwargs)
 
 
 class GoogleAIResource(_GoogleBaseResource):
-    def overview(self, *, url: str, **kwargs: Any) -> GoogleAIOverviewResponse:
-        return self._typed_call("ai_overview", GoogleAIOverviewResponse, url=url, **kwargs)
+    def overview(self, *, url: str, **kwargs: Any) -> JSONDict:
+        return self._json_call("ai_overview", url=url, **kwargs)
 
-    def mode(self, *, query: str, **kwargs: Any) -> GoogleAIOverviewResponse:
-        return self._typed_call("ai_mode", GoogleAIOverviewResponse, query=query, **kwargs)
+    def mode(self, *, query: str, **kwargs: Any) -> JSONDict:
+        return self._json_call("ai_mode", query=query, **kwargs)
 
 
 class GoogleResource(_GoogleBaseResource):
@@ -101,11 +92,11 @@ def __init__(self, api_client: ApiClient, timeout: TimeoutValue) -> None:
         self.shopping = GoogleShoppingResource(api, timeout)
         self.ai = GoogleAIResource(api, timeout)
 
-    def search(self, *, query: str, **kwargs: Any) -> GoogleSearchResponse:
-        return self._typed_call("search", GoogleSearchResponse, query=query, **kwargs)
+    def search(self, *, query: str, **kwargs: Any) -> JSONDict:
+        return self._json_call("search", query=query, **kwargs)
 
-    def autocomplete(self, *, query: str, **kwargs: Any) -> GoogleAutocompleteResponse:
-        return self._typed_call("autocomplete", GoogleAutocompleteResponse, query=query, **kwargs)
+    def autocomplete(self, *, query: str, **kwargs: Any) -> JSONDict:
+        return self._json_call("autocomplete", query=query, **kwargs)
 
 
 class Client:
diff --git a/tests/test_client.py b/tests/test_client.py

Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,3 @@`
`1`	`1`	`"""Package version."""`
`2`	`2`
`3`		`-__version__ = "2.0.0"`
	`3`	`+__version__ = "3.0.0"`