thordata-sdk 0.3.0__py3-none-any.whl → 0.3.1__py3-none-any.whl

thordata/__init__.py

@@ -5,7 +5,7 @@ from .async_client import AsyncThordataClient
 from .enums import Engine, GoogleSearchType
 
 # Package version
-__version__ = "0.3.0"
+__version__ = "0.3.1"
 
 # Explicitly export classes to simplify user imports
 __all__ = [

thordata/client.py

@@ -2,7 +2,7 @@ import requests
 import logging
 import json
 import base64
-from typing import Dict, Any, Union, Optional
+from typing import Dict, Any, Union, Optional, List
 
 from .enums import Engine
 from .parameters import normalize_serp_params
@@ -53,6 +53,7 @@ class ThordataClient:
         self.base_url = "https://scraperapi.thordata.com"
         self.universal_url = "https://universalapi.thordata.com"
         self.api_url = "https://api.thordata.com/api/web-scraper-api"
+        self.locations_url = "https://api.thordata.com/api/locations"
 
         self.SERP_API_URL = f"{self.base_url}/request"
         self.UNIVERSAL_API_URL = f"{self.universal_url}/request"
@@ -349,4 +350,137 @@ class ThordataClient:
             raise Exception(f"API returned error: {data}")
         except Exception as e:
             logger.error(f"Get Result Failed: {e}")
-            raise
+            raise
+        
+    def _get_locations(self, endpoint: str, params: Dict[str, str]) -> List[Dict[str, Any]]:
+        """
+        Internal helper to call the public locations API.
+
+        Args:
+            endpoint: One of 'countries', 'states', 'cities', 'asn'.
+            params: Query parameters (must include token, key, proxy_type, etc.)
+
+        Returns:
+            List of location records from the 'data' field.
+
+        Raises:
+            RuntimeError: If token/key are missing or API returns an error code.
+        """
+        if not self.public_token or not self.public_key:
+            raise RuntimeError(
+                "Public API token/key are required for locations endpoints. "
+                "Please provide 'public_token' and 'public_key' when "
+                "initializing ThordataClient."
+            )
+
+        url = f"{self.locations_url}/{endpoint}"
+        logger.info("Locations API request: %s", url)
+
+        # Use a direct requests.get here; no need to go through the proxy gateway.
+        response = requests.get(
+            url,
+            params=params,
+            timeout=30,
+        )
+        response.raise_for_status()
+
+        data = response.json()
+        if isinstance(data, dict):
+            code = data.get("code")
+            if code is not None and code != 200:
+                msg = data.get("msg", "")
+                raise RuntimeError(
+                    f"Locations API error ({endpoint}): code={code}, msg={msg}"
+                )
+            return data.get("data") or []
+        # Fallback: if backend ever returns a list directly
+        if isinstance(data, list):
+            return data
+        return []
+    
+    def list_countries(self, proxy_type: int = 1) -> List[Dict[str, Any]]:
+        """
+        List supported countries for Thordata residential or unlimited proxies.
+
+        Args:
+            proxy_type (int): 1 for residential proxies, 2 for unlimited proxies.
+
+        Returns:
+            List[Dict[str, Any]]: Each record contains 'country_code' and 'country_name'.
+        """
+        params = {
+            "token": self.public_token,
+            "key": self.public_key,
+            "proxy_type": str(proxy_type),
+        }
+        return self._get_locations("countries", params)
+
+    def list_states(self, country_code: str, proxy_type: int = 1) -> List[Dict[str, Any]]:
+        """
+        List supported states for a given country.
+
+        Args:
+            country_code (str): Country code (e.g., 'US').
+            proxy_type (int): 1 for residential proxies, 2 for unlimited proxies.
+
+        Returns:
+            List[Dict[str, Any]]: Each record contains 'state_code' and 'state_name'.
+        """
+        params = {
+            "token": self.public_token,
+            "key": self.public_key,
+            "proxy_type": str(proxy_type),
+            "country_code": country_code,
+        }
+        return self._get_locations("states", params)
+
+    def list_cities(
+        self,
+        country_code: str,
+        state_code: Optional[str] = None,
+        proxy_type: int = 1,
+    ) -> List[Dict[str, Any]]:
+        """
+        List supported cities for a given country (and optional state).
+
+        Args:
+            country_code (str): Country code (e.g., 'US').
+            state_code (Optional[str]): State code (e.g., 'alabama'), if applicable.
+            proxy_type (int): 1 for residential proxies, 2 for unlimited proxies.
+
+        Returns:
+            List[Dict[str, Any]]: Each record contains 'city_code' and 'city_name'.
+        """
+        params: Dict[str, str] = {
+            "token": self.public_token,
+            "key": self.public_key,
+            "proxy_type": str(proxy_type),
+            "country_code": country_code,
+        }
+        if state_code:
+            params["state_code"] = state_code
+
+        return self._get_locations("cities", params)
+
+    def list_asn(
+        self,
+        country_code: str,
+        proxy_type: int = 1,
+    ) -> List[Dict[str, Any]]:
+        """
+        List supported ASNs for a given country.
+
+        Args:
+            country_code (str): Country code (e.g., 'US').
+            proxy_type (int): 1 for residential proxies, 2 for unlimited proxies.
+
+        Returns:
+            List[Dict[str, Any]]: Each record contains 'asn_code' and 'asn_name'.
+        """
+        params = {
+            "token": self.public_token,
+            "key": self.public_key,
+            "proxy_type": str(proxy_type),
+            "country_code": country_code,
+        }
+        return self._get_locations("asn", params)

{thordata_sdk-0.3.0.dist-info → thordata_sdk-0.3.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: thordata-sdk
-Version: 0.3.0
+Version: 0.3.1
 Summary: The Official Python SDK for Thordata - AI Data Infrastructure & Proxy Network.
 Author-email: Thordata Developer Team <support@thordata.com>
 License: Apache-2.0
@@ -36,6 +36,9 @@ Dynamic: license-file
 </h4>
 
 <p align="center">
+  <a href="https://github.com/Thordata/thordata-python-sdk/actions/workflows/ci.yml">
+    <img src="https://github.com/Thordata/thordata-python-sdk/actions/workflows/ci.yml/badge.svg" alt="CI">
+  </a>
   <a href="https://pypi.org/project/thordata-sdk/">
     <img src="https://img.shields.io/pypi/v/thordata-sdk?color=blue" alt="PyPI version">
   </a>

thordata_sdk-0.3.1.dist-info/RECORD

@@ -0,0 +1,10 @@
+thordata/__init__.py,sha256=iv2luaDxUmcWTqScu08gGJfocUZr6pSwtzJs2akZ1Gg,365
+thordata/async_client.py,sha256=cpBtRIzr8oH6GuZs8gTh505tGYYV1aRFBUzbtmFOfEg,9717
+thordata/client.py,sha256=WVIvIZTACEpw9NaTbGtIkMGUlfliFL7kNGdCoTxxsUI,17193
+thordata/enums.py,sha256=PGUCQX3jw5a9mX8_JfhuyoR1WriWjWQpAgibVP_bpdM,679
+thordata/parameters.py,sha256=1lNx_BSS8ztBKEj_MXZMaIQQ9_W3EAlS-VFiBqSWb9E,1841
+thordata_sdk-0.3.1.dist-info/licenses/LICENSE,sha256=HrhfyXIkWY2tGFK11kg7vPCqhgh5DcxleloqdhrpyMY,11558
+thordata_sdk-0.3.1.dist-info/METADATA,sha256=NMq7Be240zn2q3MlUUg2Dmo4NFoQtDMgkRAGzjg_yjc,5901
+thordata_sdk-0.3.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+thordata_sdk-0.3.1.dist-info/top_level.txt,sha256=Z8R_07m0lXCCSb1hapL9_nxMtyO3rf_9wOvq4n9u2Hg,9
+thordata_sdk-0.3.1.dist-info/RECORD,,

thordata_sdk-0.3.0.dist-info/RECORD

@@ -1,10 +0,0 @@
-thordata/__init__.py,sha256=HVb6cHBsYRFoA1Sf_y_WSZ88vGV3DsT67rCdbZSuUYE,365
-thordata/async_client.py,sha256=cpBtRIzr8oH6GuZs8gTh505tGYYV1aRFBUzbtmFOfEg,9717
-thordata/client.py,sha256=w_EXs6CLM2qFtFPNU-x_Li66LEH1j7pQb2ca2MDKqyA,12432
-thordata/enums.py,sha256=PGUCQX3jw5a9mX8_JfhuyoR1WriWjWQpAgibVP_bpdM,679
-thordata/parameters.py,sha256=1lNx_BSS8ztBKEj_MXZMaIQQ9_W3EAlS-VFiBqSWb9E,1841
-thordata_sdk-0.3.0.dist-info/licenses/LICENSE,sha256=HrhfyXIkWY2tGFK11kg7vPCqhgh5DcxleloqdhrpyMY,11558
-thordata_sdk-0.3.0.dist-info/METADATA,sha256=Yj6W3vSLkkUhSXTj6AK4AaMfdlJvGOVaK6cFI2MNqV8,5697
-thordata_sdk-0.3.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-thordata_sdk-0.3.0.dist-info/top_level.txt,sha256=Z8R_07m0lXCCSb1hapL9_nxMtyO3rf_9wOvq4n9u2Hg,9
-thordata_sdk-0.3.0.dist-info/RECORD,,