listingsapi 0.5.0__py3-none-any.whl

listingsapi/__init__.py

@@ -0,0 +1,46 @@
+"""listingsAPI Python SDK — listings, reviews, posts, and analytics for local marketing.
+
+Example:
+    import listingsapi
+
+    client = listingsapi.ListingsAPI()  # reads LISTINGSAPI_KEY from env
+
+    for location in client.locations.list(first=10):
+        print(location.name, location.city)
+"""
+
+from listingsapi._client import ListingsAPI
+from listingsapi._types import APIObject, SyncPage
+from listingsapi.exceptions import (
+    APIConnectionError,
+    APIError,
+    AuthenticationError,
+    InternalServerError,
+    ListingsAPIError,
+    NotFoundError,
+    PermissionDeniedError,
+    RateLimitError,
+    ValidationError,
+)
+
+__version__ = "0.5.0"
+
+__all__ = [
+    # Client
+    "ListingsAPI",
+    # Types
+    "APIObject",
+    "SyncPage",
+    # Exceptions
+    "ListingsAPIError",
+    "APIError",
+    "AuthenticationError",
+    "PermissionDeniedError",
+    "NotFoundError",
+    "ValidationError",
+    "RateLimitError",
+    "InternalServerError",
+    "APIConnectionError",
+    # Version
+    "__version__",
+]

listingsapi/_client.py

@@ -0,0 +1,269 @@
+"""Main listingsAPI client."""
+
+from __future__ import annotations
+
+import logging
+import os
+from typing import Any
+
+import requests
+from requests.adapters import HTTPAdapter
+from urllib3.util.retry import Retry
+
+from listingsapi._types import APIObject
+from listingsapi._utils import encode_location_id
+from listingsapi.exceptions import (
+    APIConnectionError,
+    APIError,
+    AuthenticationError,
+    InternalServerError,
+    NotFoundError,
+    PermissionDeniedError,
+    RateLimitError,
+    ValidationError,
+)
+
+logger = logging.getLogger("listingsapi")
+
+DEFAULT_BASE_URL = "https://listingsapi.com"
+DEFAULT_TIMEOUT = 240.0
+DEFAULT_MAX_RETRIES = 2
+
+
+class ListingsAPI:
+    """Client for the listingsAPI platform.
+
+    Example:
+        import listingsapi
+
+        # Reads LISTINGSAPI_KEY from environment
+        client = listingsapi.ListingsAPI()
+
+        # Or pass explicitly
+        client = listingsapi.ListingsAPI(api_key="your-key")
+
+        # With custom config
+        client = listingsapi.ListingsAPI(api_key="...", timeout=60.0, max_retries=3)
+
+        # Use resources
+        page = client.locations.list(first=10)
+        for location in page:
+            print(location.name, location.city)
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str | None = None,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+    ):
+        self.api_key = api_key or os.environ.get("LISTINGSAPI_KEY")
+        if not self.api_key:
+            raise AuthenticationError(
+                "No API key provided. Set the LISTINGSAPI_KEY environment variable "
+                "or pass api_key= to ListingsAPI().",
+                status_code=401,
+            )
+
+        self._base_url = (base_url or DEFAULT_BASE_URL).rstrip("/")
+        self._timeout = timeout
+
+        self._session = requests.Session()
+        self._session.headers.update(
+            {
+                "Authorization": f"API {self.api_key}",
+                "Content-Type": "application/json",
+            }
+        )
+
+        retry = Retry(
+            total=max_retries,
+            backoff_factor=0.5,
+            status_forcelist=[429, 500, 502, 503, 504],
+            allowed_methods=["GET", "POST"],
+            respect_retry_after_header=True,
+        )
+        adapter = HTTPAdapter(max_retries=retry)
+        self._session.mount("https://", adapter)
+        self._session.mount("http://", adapter)
+
+        # Resources — lazy imports to avoid circular deps
+        from listingsapi.resources import (
+            Analytics,
+            ConnectedAccounts,
+            Listings,
+            Locations,
+            Photos,
+            Posts,
+            Reviews,
+            Workflows,
+        )
+
+        self.locations = Locations(self)
+        self.reviews = Reviews(self)
+        self.posts = Posts(self)
+        self.listings = Listings(self)
+        self.analytics = Analytics(self)
+        self.connected_accounts = ConnectedAccounts(self)
+        self.photos = Photos(self)
+        self.workflows = Workflows(self)
+
+    # --- HTTP methods (used by resources) ---
+
+    def _get(self, path: str, params: dict | None = None) -> dict[str, Any]:
+        url = f"{self._base_url}/api/v4/{path}"
+        logger.debug("GET %s params=%s", url, params)
+        try:
+            response = self._session.get(url, params=params or {}, timeout=self._timeout)
+        except requests.ConnectionError as e:
+            raise APIConnectionError(f"Connection error: {e}") from e
+        except requests.Timeout as e:
+            raise APIConnectionError(f"Request timed out: {e}") from e
+        return self._handle_response(response)
+
+    def _post(self, path: str, json_body: dict[str, Any]) -> dict[str, Any]:
+        url = f"{self._base_url}/api/v4/{path}"
+        logger.debug("POST %s", url)
+        try:
+            response = self._session.post(url, json=json_body, timeout=self._timeout)
+        except requests.ConnectionError as e:
+            raise APIConnectionError(f"Connection error: {e}") from e
+        except requests.Timeout as e:
+            raise APIConnectionError(f"Request timed out: {e}") from e
+        data = self._handle_response(response)
+        self._raise_for_mutation_errors(data, response)
+        return data
+
+    def _delete(self, path: str, json_body: dict[str, Any] | None = None) -> dict[str, Any]:
+        url = f"{self._base_url}/api/v4/{path}"
+        logger.debug("DELETE %s", url)
+        try:
+            response = self._session.delete(url, json=json_body, timeout=self._timeout)
+        except requests.ConnectionError as e:
+            raise APIConnectionError(f"Connection error: {e}") from e
+        except requests.Timeout as e:
+            raise APIConnectionError(f"Request timed out: {e}") from e
+        data = self._handle_response(response)
+        self._raise_for_mutation_errors(data, response)
+        return data
+
+    def _location_get(
+        self, location_id: str | int, path_suffix: str, params: dict | None = None
+    ) -> dict[str, Any]:
+        encoded_id = encode_location_id(location_id)
+        return self._get(f"locations/{encoded_id}/{path_suffix}", params)
+
+    def _handle_response(self, response: requests.Response) -> dict[str, Any]:
+        if response.ok:
+            data = response.json()
+            if isinstance(data, dict):
+                errors = _parse_error_entries(data.get("errors"))
+                if errors:
+                    raise _exception_for_errors(errors, response)
+            return data
+
+        status = response.status_code
+        body = response.text
+        msg = f"API request failed: {status}"
+
+        if status == 401:
+            raise AuthenticationError(msg, status_code=status, response_body=body)
+        elif status == 403:
+            raise PermissionDeniedError(msg, status_code=status, response_body=body)
+        elif status == 404:
+            raise NotFoundError(msg, status_code=status, response_body=body)
+        elif status == 429:
+            retry_after = response.headers.get("Retry-After")
+            raise RateLimitError(msg, status_code=status, response_body=body, retry_after=retry_after)
+        elif status in (400, 422):
+            raise ValidationError(msg, status_code=status, response_body=body)
+        elif status >= 500:
+            raise InternalServerError(msg, status_code=status, response_body=body)
+        else:
+            raise APIError(msg, status_code=status, response_body=body)
+
+    def _raise_for_mutation_errors(self, data: dict[str, Any], response: requests.Response) -> None:
+        if not isinstance(data, dict):
+            return
+        payload = data.get("data")
+        if not isinstance(payload, dict):
+            return
+        for result in payload.values():
+            if not isinstance(result, dict):
+                continue
+            errors = _parse_error_entries(result.get("errors"))
+            if errors or result.get("success") is False:
+                if not errors:
+                    errors = [{"code": None, "message": "The API reported success=false", "context": {}}]
+                raise ValidationError(
+                    "API request failed",
+                    status_code=response.status_code,
+                    response_body=response.text,
+                    errors=errors,
+                )
+
+    # --- Account-level convenience methods ---
+
+    def plan_sites(self) -> list[APIObject]:
+        """Get supported directories for your plan."""
+        data = self._get("plan-sites")
+        items = data.get("data", {}).get("planSites") or []
+        return [APIObject(item) for item in items]
+
+    def subcategories(self) -> list[APIObject]:
+        """Get business subcategories (use the databaseId as subCategoryId when creating locations)."""
+        data = self._get("sub-categories")
+        items = data.get("data", {}).get("subcategories") or []
+        return [APIObject(item) for item in items]
+
+    def countries(self) -> list[APIObject]:
+        """Get supported countries and states (ISO codes)."""
+        data = self._get("countries")
+        items = data.get("data", {}).get("supportedCountries") or []
+        return [APIObject(item) for item in items]
+
+    def subscriptions(self) -> list[APIObject]:
+        """Get active subscriptions for the account."""
+        data = self._get("subscriptions")
+        items = data.get("data", {}).get("activeSubscriptions") or []
+        return [APIObject(item) for item in items]
+
+
+def _parse_error_entries(raw: Any) -> list[dict[str, Any]]:
+    if not raw:
+        return []
+    entries: list[dict[str, Any]] = []
+    for item in raw if isinstance(raw, list) else [raw]:
+        if isinstance(item, dict):
+            entries.append(
+                {
+                    "code": item.get("code"),
+                    "message": item.get("message") or str(item),
+                    "context": item.get("context") or {},
+                }
+            )
+        else:
+            entries.append({"code": None, "message": str(item), "context": {}})
+    return entries
+
+
+_AUTH_CODES = {"SY90005", "SY90001"}
+_PERMISSION_CODES = {"SY90003"}
+
+
+def _exception_for_errors(errors: list[dict[str, Any]], response: requests.Response) -> APIError:
+    codes = {e["code"] for e in errors if e.get("code")}
+    kwargs: dict[str, Any] = {
+        "status_code": response.status_code,
+        "response_body": response.text,
+        "errors": errors,
+    }
+    if codes & _AUTH_CODES:
+        return AuthenticationError("Authentication failed", **kwargs)
+    if codes & _PERMISSION_CODES:
+        return PermissionDeniedError("Permission denied", **kwargs)
+    if codes == {"RATE_LIMITED"}:
+        return RateLimitError("Rate limit exceeded", **kwargs)
+    return APIError("API request failed", **kwargs)

listingsapi/_types.py

@@ -0,0 +1,137 @@
+"""Response types for the listingsAPI SDK."""
+
+from __future__ import annotations
+
+from typing import Any, Callable, Generator
+
+
+class APIObject:
+    """API response object with attribute access. Works like a dict but with dot notation.
+
+    Example:
+        location = client.locations.retrieve(16808)
+        print(location.name)        # "StarBucks New York"
+        print(location.city)        # "New York"
+        print(location["stateIso"]) # "NY"  (dict-style also works)
+        print(location.to_dict())   # raw dict
+    """
+
+    def __init__(self, data: dict[str, Any] | None = None):
+        object.__setattr__(self, "_data", data or {})
+
+    def __getattr__(self, name: str) -> Any:
+        try:
+            value = self._data[name]
+        except KeyError:
+            raise AttributeError(f"'{type(self).__name__}' has no attribute '{name}'")
+        if isinstance(value, dict):
+            return APIObject(value)
+        if isinstance(value, list):
+            return [APIObject(v) if isinstance(v, dict) else v for v in value]
+        return value
+
+    def __getitem__(self, key: str) -> Any:
+        return self._data[key]
+
+    def __contains__(self, key: str) -> bool:
+        return key in self._data
+
+    def __iter__(self):
+        return iter(self._data)
+
+    def __len__(self) -> int:
+        return len(self._data)
+
+    def keys(self):
+        return self._data.keys()
+
+    def values(self):
+        return self._data.values()
+
+    def items(self):
+        return self._data.items()
+
+    def __repr__(self) -> str:
+        return repr(self._data)
+
+    def __str__(self) -> str:
+        return str(self._data)
+
+    def __bool__(self) -> bool:
+        return bool(self._data)
+
+    def get(self, key: str, default: Any = None) -> Any:
+        return self._data.get(key, default)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Return the raw dict."""
+        return self._data
+
+
+class SyncPage:
+    """A page of results with built-in pagination.
+
+    Example:
+        page = client.locations.list(first=10)
+        for location in page:
+            print(location.name)
+
+        # Auto-paginate through all results
+        for location in page.auto_paging_iter():
+            print(location.name)
+
+        # Manual pagination
+        if page.has_more:
+            next_page = page.next_page()
+    """
+
+    def __init__(
+        self,
+        data: list[dict[str, Any]],
+        has_more: bool = False,
+        end_cursor: str | None = None,
+        total: int | None = None,
+        _fetch_next: Callable[..., "SyncPage"] | None = None,
+    ):
+        self.data: list[APIObject] = [
+            APIObject(item) if isinstance(item, dict) else item for item in data
+        ]
+        self.has_more = has_more
+        self.total = total
+        self._end_cursor = end_cursor
+        self._fetch_next = _fetch_next
+
+    def __iter__(self):
+        return iter(self.data)
+
+    def __len__(self) -> int:
+        return len(self.data)
+
+    def __bool__(self) -> bool:
+        return bool(self.data)
+
+    def __getitem__(self, index):
+        return self.data[index]
+
+    def __repr__(self) -> str:
+        return f"SyncPage(items={len(self.data)}, has_more={self.has_more})"
+
+    def next_page(self) -> SyncPage | None:
+        """Fetch the next page of results, or None if no more pages."""
+        if not self.has_more or not self._fetch_next:
+            return None
+        return self._fetch_next(self._end_cursor)
+
+    def auto_paging_iter(self) -> Generator[APIObject, None, None]:
+        """Iterate through all pages automatically.
+
+        Example:
+            for location in client.locations.list(first=10).auto_paging_iter():
+                print(location.name)
+        """
+        page: SyncPage | None = self
+        while page is not None:
+            yield from page.data
+            if not page.has_more:
+                break
+            page = page.next_page()

listingsapi/_utils.py

@@ -0,0 +1,15 @@
+"""Internal utilities."""
+
+from __future__ import annotations
+
+import base64
+
+
+def encode_location_id(id_value: str | int) -> str:
+    """Convert a numeric location ID to base64-encoded form, or return as-is if already encoded."""
+    if isinstance(id_value, int):
+        return base64.b64encode(f"Location:{id_value}".encode()).decode("ascii")
+    s = str(id_value).strip()
+    if s.isdigit():
+        return base64.b64encode(f"Location:{s}".encode()).decode("ascii")
+    return s

listingsapi/exceptions.py

@@ -0,0 +1,104 @@
+"""listingsAPI SDK exceptions. Catch specific errors for fine-grained handling."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class ListingsAPIError(Exception):
+    """Base exception for all listingsAPI SDK errors."""
+
+
+class APIError(ListingsAPIError):
+    """Raised when the API reports a failure.
+
+    Covers both non-2xx HTTP responses and error payloads the API returns with
+    HTTP 200 (the platform reports auth and validation failures in an errors[]
+    body; mutations report success=false plus errors[]).
+
+    Attributes:
+        status_code: HTTP status code of the response (may be 200 for
+            payload-level errors).
+        response_body: Raw response text from the API, when available.
+        code: The first API error code (e.g. "SY10005"), when the API sent one.
+        errors: Parsed API error entries, each normalized to a dict with
+            "code", "message", and "context" keys.
+
+    Example:
+        try:
+            client.locations.list()
+        except listingsapi.APIError as e:
+            print(e.status_code, e.code)
+            for err in e.errors:
+                print(err["code"], err["message"])
+    """
+
+    def __init__(
+        self,
+        message: str,
+        status_code: int | None = None,
+        response_body: str | None = None,
+        errors: list[dict[str, Any]] | None = None,
+    ):
+        self.status_code = status_code
+        self.response_body = response_body
+        self.errors = errors or []
+        self.code = self.errors[0].get("code") if self.errors else None
+        detail = "; ".join(
+            f"{e['code']}: {e['message']}" if e.get("code") else str(e.get("message", ""))
+            for e in self.errors
+        )
+        if detail:
+            full = f"{message} — {detail}"
+        elif response_body:
+            full = f"{message} — {response_body}"
+        else:
+            full = message
+        super().__init__(full)
+
+
+class AuthenticationError(APIError):
+    """401 — Invalid or missing API key."""
+
+
+class PermissionDeniedError(APIError):
+    """403 — Insufficient permissions for this action."""
+
+
+class NotFoundError(APIError):
+    """404 — Resource not found."""
+
+
+class ValidationError(APIError):
+    """400/422 — Invalid request parameters."""
+
+
+class RateLimitError(APIError):
+    """429 — Too many requests. Check retry_after for backoff.
+
+    Attributes:
+        retry_after: Seconds to wait before retrying (from Retry-After header), or None.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        status_code: int | None = None,
+        response_body: str | None = None,
+        retry_after: str | None = None,
+        errors: list[dict[str, Any]] | None = None,
+    ):
+        super().__init__(message, status_code=status_code, response_body=response_body, errors=errors)
+        self.retry_after = float(retry_after) if retry_after else None
+
+
+class InternalServerError(APIError):
+    """5xx — Server-side error. Safe to retry."""
+
+
+class APIConnectionError(ListingsAPIError):
+    """Network failure — could not reach the API."""
+
+
+# Backward compat
+APIError = APIError

listingsapi/resources/__init__.py

@@ -0,0 +1,21 @@
+"""listingsAPI resources."""
+
+from listingsapi.resources.locations import Locations
+from listingsapi.resources.posts import Posts
+from listingsapi.resources.reviews import Reviews
+from listingsapi.resources.listings import Listings
+from listingsapi.resources.analytics import Analytics
+from listingsapi.resources.connected_accounts import ConnectedAccounts
+from listingsapi.resources.photos import Photos
+from listingsapi.resources.workflows import Workflows
+
+__all__ = [
+    "Locations",
+    "Posts",
+    "Reviews",
+    "Listings",
+    "Analytics",
+    "ConnectedAccounts",
+    "Photos",
+    "Workflows",
+]

listingsapi/resources/_base.py

@@ -0,0 +1,29 @@
+"""Base class for API resources."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from listingsapi._client import ListingsAPI
+
+
+class APIResource:
+    """Base class that all resources inherit from. Provides access to the client's HTTP methods."""
+
+    def __init__(self, client: ListingsAPI) -> None:
+        self._client = client
+
+    def _get(self, path: str, params: dict | None = None) -> dict[str, Any]:
+        return self._client._get(path, params)
+
+    def _post(self, path: str, json_body: dict[str, Any]) -> dict[str, Any]:
+        return self._client._post(path, json_body)
+
+    def _delete(self, path: str, json_body: dict[str, Any] | None = None) -> dict[str, Any]:
+        return self._client._delete(path, json_body)
+
+    def _location_get(
+        self, location_id: str | int, path_suffix: str, params: dict | None = None
+    ) -> dict[str, Any]:
+        return self._client._location_get(location_id, path_suffix, params)

listingsapi/resources/analytics.py

@@ -0,0 +1,54 @@
+"""Analytics resource — client.analytics.*"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from listingsapi._types import APIObject
+from listingsapi.resources._base import APIResource
+
+
+class Analytics(APIResource):
+    """Profile and ranking analytics.
+
+    Example:
+        google = client.analytics.google(16808, from_date="2024-01-01")
+        bing = client.analytics.bing(16808)
+    """
+
+    def google(
+        self, location_id: str | int, *, from_date: str | None = None, to_date: str | None = None
+    ) -> APIObject:
+        """Get Google (GMB) profile analytics for a location."""
+        params: dict[str, str] = {}
+        if from_date:
+            params["fromDate"] = from_date
+        if to_date:
+            params["toDate"] = to_date
+        data = self._location_get(location_id, "google-analytics", params)
+        return APIObject(data.get("data", {}).get("googleInsights") or {})
+
+    def bing(
+        self, location_id: str | int, *, from_date: str | None = None, to_date: str | None = None
+    ) -> APIObject:
+        """Get Bing profile analytics for a location."""
+        params: dict[str, str] = {}
+        if from_date:
+            params["fromDate"] = from_date
+        if to_date:
+            params["toDate"] = to_date
+        data = self._location_get(location_id, "bing-analytics", params)
+        return APIObject(data.get("data", {}).get("bingInsights") or {})
+
+    def facebook(
+        self, location_id: str | int, *, from_date: str | None = None, to_date: str | None = None
+    ) -> APIObject:
+        """Get Facebook page analytics for a location."""
+        params: dict[str, str] = {}
+        if from_date:
+            params["fromDate"] = from_date
+        if to_date:
+            params["toDate"] = to_date
+        data = self._location_get(location_id, "facebook-analytics", params)
+        return APIObject(data.get("data", {}).get("facebookInsights") or {})
+