apish-sdk 0.1.0__tar.gz

apish_sdk-0.1.0/.gitignore

@@ -0,0 +1,5 @@
+node_modules/
+dist/
+*.egg-info/
+__pycache__/
+.pytest_cache/

apish_sdk-0.1.0/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 api.sh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

apish_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,98 @@
+Metadata-Version: 2.3
+Name: apish-sdk
+Version: 0.1.0
+Summary: Official client for api.sh: public web data (TikTok, Instagram, Amazon, Zillow, Google and 70+ platforms) as clean JSON.
+Project-URL: Homepage, https://api.sh
+Project-URL: Documentation, https://api.sh/docs/sdks
+Author-email: "api.sh" <support@api.sh>
+License: MIT
+License-File: LICENSE
+Keywords: amazon,api.sh,apish,instagram,json,scraping,serp,tiktok,web scraping
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx<1,>=0.24
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.2; extra == 'langchain'
+Description-Content-Type: text/markdown
+
+# api.sh for Python
+
+Official Python client for [api.sh](https://api.sh): public web data from TikTok, Instagram, Amazon, Zillow, Google and 70+ platforms as clean JSON. Every endpoint is a typed method.
+
+```sh
+pip install api-sh
+```
+
+```python
+from apish import Apish
+
+apish = Apish()  # reads APISH_API_KEY; or Apish("ash_live_…")  (https://app.api.sh/keys)
+
+profile = apish.tiktok.profile(username="nasa")
+print(profile["followers"], profile.meta.credits_used, profile.meta.request_id)
+
+results = apish.amazon.search(q="headphones", options={"raw": False})
+```
+
+Python 3.9+, sync (`Apish`) and asyncio (`AsyncApish`).
+
+## Calls
+
+- `apish.<platform>.<endpoint>(**params, options=...)`: one method per endpoint, with keyword-only typed parameters and the price in its docstring.
+- `apish.call(route, params, options)`: any route, e.g. `apish.call("/reddit/v1/subreddit", {"subreddit": "python"})`.
+- Options: `raw` (False leaves out raw source blocks), `fields`, `fresh`, `output` ("csv" / "ndjson" returns text), `timeout`, `max_retries`.
+- Results are dicts with `.meta` (`request_id`, `credits_used`, `credits_remaining`, `status`, `seconds`).
+- Retries 502/503/504 and network errors with backoff (failed calls are never charged).
+
+```python
+for page in apish.paginate("/reddit/v1/subreddit", {"subreddit": "python"}, max_pages=5):
+    print(len(page["posts"]))
+
+from apish import ApishError
+try:
+    apish.zillow.property(url=url)
+except ApishError as e:
+    print(e.status, e.message, e.insufficient_credits, e.spend_limit, e.request_id)
+```
+
+## Async
+
+```python
+import asyncio
+from apish import AsyncApish
+
+async def main():
+    async with AsyncApish() as apish:
+        print((await apish.reddit.subreddit(subreddit="python"))["posts"][0]["title"])
+
+asyncio.run(main())
+```
+
+## Account (free)
+
+```python
+apish.account.get()            # balance, plan, spend, limits
+apish.account.usage(days=30)
+apish.account.logs(status="error")
+apish.account.result(request_id)   # a past response again, free, 30 days
+```
+
+## AI agents
+
+```python
+from apish.tools import openai_tools, anthropic_tools, run_tool
+tools = openai_tools()             # apish_search + apish_call (or openai_tools(["/tiktok/v1/profile"]))
+text = run_tool(apish, name, arguments)   # when the model calls a tool
+
+# LangChain:  pip install "api-sh[langchain]"
+from apish.langchain import apish_tools
+tools = apish_tools(apish)
+```
+
+For Claude Desktop, Cursor and other MCP clients, use the [MCP server](https://api.sh/mcp).
+
+Docs: https://api.sh/docs/sdks · License: MIT

apish_sdk-0.1.0/README.md

@@ -0,0 +1,77 @@
+# api.sh for Python
+
+Official Python client for [api.sh](https://api.sh): public web data from TikTok, Instagram, Amazon, Zillow, Google and 70+ platforms as clean JSON. Every endpoint is a typed method.
+
+```sh
+pip install api-sh
+```
+
+```python
+from apish import Apish
+
+apish = Apish()  # reads APISH_API_KEY; or Apish("ash_live_…")  (https://app.api.sh/keys)
+
+profile = apish.tiktok.profile(username="nasa")
+print(profile["followers"], profile.meta.credits_used, profile.meta.request_id)
+
+results = apish.amazon.search(q="headphones", options={"raw": False})
+```
+
+Python 3.9+, sync (`Apish`) and asyncio (`AsyncApish`).
+
+## Calls
+
+- `apish.<platform>.<endpoint>(**params, options=...)`: one method per endpoint, with keyword-only typed parameters and the price in its docstring.
+- `apish.call(route, params, options)`: any route, e.g. `apish.call("/reddit/v1/subreddit", {"subreddit": "python"})`.
+- Options: `raw` (False leaves out raw source blocks), `fields`, `fresh`, `output` ("csv" / "ndjson" returns text), `timeout`, `max_retries`.
+- Results are dicts with `.meta` (`request_id`, `credits_used`, `credits_remaining`, `status`, `seconds`).
+- Retries 502/503/504 and network errors with backoff (failed calls are never charged).
+
+```python
+for page in apish.paginate("/reddit/v1/subreddit", {"subreddit": "python"}, max_pages=5):
+    print(len(page["posts"]))
+
+from apish import ApishError
+try:
+    apish.zillow.property(url=url)
+except ApishError as e:
+    print(e.status, e.message, e.insufficient_credits, e.spend_limit, e.request_id)
+```
+
+## Async
+
+```python
+import asyncio
+from apish import AsyncApish
+
+async def main():
+    async with AsyncApish() as apish:
+        print((await apish.reddit.subreddit(subreddit="python"))["posts"][0]["title"])
+
+asyncio.run(main())
+```
+
+## Account (free)
+
+```python
+apish.account.get()            # balance, plan, spend, limits
+apish.account.usage(days=30)
+apish.account.logs(status="error")
+apish.account.result(request_id)   # a past response again, free, 30 days
+```
+
+## AI agents
+
+```python
+from apish.tools import openai_tools, anthropic_tools, run_tool
+tools = openai_tools()             # apish_search + apish_call (or openai_tools(["/tiktok/v1/profile"]))
+text = run_tool(apish, name, arguments)   # when the model calls a tool
+
+# LangChain:  pip install "api-sh[langchain]"
+from apish.langchain import apish_tools
+tools = apish_tools(apish)
+```
+
+For Claude Desktop, Cursor and other MCP clients, use the [MCP server](https://api.sh/mcp).
+
+Docs: https://api.sh/docs/sdks · License: MIT

apish_sdk-0.1.0/apish/__init__.py

@@ -0,0 +1,13 @@
+"""Official Python client for api.sh: public web data from 70+ platforms as clean JSON.
+
+    from apish import Apish
+    apish = Apish()                       # reads APISH_API_KEY
+    print(apish.reddit.subreddit(subreddit="python")["posts"][0]["title"])
+
+Docs: https://api.sh/docs/sdks
+"""
+from ._client import DEFAULT_BASE_URL, Apish, AsyncApish, __version__
+from ._types import CallMeta, CallOptions, Result, TextResult
+from .errors import ApishError
+
+__all__ = ["Apish", "AsyncApish", "ApishError", "CallMeta", "CallOptions", "Result", "TextResult", "DEFAULT_BASE_URL", "__version__"]

apish_sdk-0.1.0/apish/_client.py

@@ -0,0 +1,258 @@
+from __future__ import annotations
+
+import os
+import random
+import time
+import asyncio
+from typing import Any, AsyncIterator, Dict, Iterator, Optional, Union
+from urllib.parse import quote
+
+import httpx
+
+from ._endpoints import CREDITS, PAGINATION, AsyncPlatforms, Platforms
+from ._types import CallMeta, CallOptions, Result, TextResult
+from .errors import ApishError
+
+__version__ = "0.1.0"
+DEFAULT_BASE_URL = "https://api.api.sh"
+
+
+def _query(params: Dict[str, Any], options: Optional[CallOptions]) -> Dict[str, str]:
+    q: Dict[str, str] = {}
+    for k, v in params.items():
+        if v is None or v == "":
+            continue
+        q[k] = ("true" if v else "false") if isinstance(v, bool) else str(v)
+    o = options or {}
+    if "raw" in o:
+        q["raw"] = "1" if o["raw"] else "0"
+    if o.get("fields"):
+        f = o["fields"]
+        q["fields"] = f if isinstance(f, str) else ",".join(f)
+    if o.get("fresh"):
+        q["fresh"] = "1"
+    if o.get("output") and o["output"] != "json":
+        q["output"] = o["output"]
+    if o.get("records"):
+        q["records"] = o["records"]
+    return q
+
+
+def _meta(res: httpx.Response, started: float) -> CallMeta:
+    rem = res.headers.get("x-credits-remaining")
+    return CallMeta(
+        request_id=res.headers.get("x-request-id"),
+        credits_used=int(res.headers.get("x-credits-used") or 0),
+        credits_remaining=int(rem) if rem is not None else None,
+        status=res.status_code,
+        seconds=round(time.monotonic() - started, 3),
+    )
+
+
+def _result(res: httpx.Response, started: float) -> Union[Result, TextResult]:
+    meta = _meta(res, started)
+    if "json" not in res.headers.get("content-type", ""):
+        return TextResult(res.text, meta)
+    data = res.json()
+    return Result(data if isinstance(data, dict) else {"items": data}, meta)
+
+
+def _error(res: httpx.Response) -> ApishError:
+    try:
+        body = res.json()
+    except ValueError:
+        body = {}
+    if not isinstance(body, dict):
+        body = {}
+    return ApishError(res.status_code, str(body.get("error") or body.get("message") or f"api.sh returned {res.status_code}"), body, res.headers.get("x-request-id"))
+
+
+def _wait(res: Optional[httpx.Response], attempt: int) -> float:
+    if res is not None:
+        try:
+            after = float(res.headers.get("retry-after", ""))
+            if after > 0:
+                return min(after, 30.0)
+        except ValueError:
+            pass
+    return min(2 ** attempt, 10) + random.random() / 4
+
+
+def _key(api_key: Optional[str]) -> str:
+    key = api_key or os.environ.get("APISH_API_KEY", "")
+    if not key:
+        raise ValueError("api.sh: pass api_key=... or set APISH_API_KEY (create a key at https://app.api.sh/keys)")
+    return key
+
+
+class Apish(Platforms):
+    """The api.sh client.
+
+        from apish import Apish
+        apish = Apish()                      # reads APISH_API_KEY
+        profile = apish.tiktok.profile(username="nasa")
+        print(profile["followers"], profile.meta.credits_used)
+
+    Every platform is an attribute (apish.amazon, apish.google_maps, ...); every endpoint a method with typed,
+    keyword-only parameters. `apish.call(route, params)` runs any route; `apish.account` covers your balance,
+    usage, logs and past responses (free).
+    """
+
+    def __init__(self, api_key: Optional[str] = None, *, base_url: str = DEFAULT_BASE_URL, timeout: float = 120.0, max_retries: int = 2, http_client: Optional[httpx.Client] = None) -> None:
+        self._key = _key(api_key)
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self._http = http_client or httpx.Client(timeout=timeout, headers={"user-agent": f"apish-python/{__version__}"})
+        super().__init__(self.call)
+        self.account = _Account(self.call)
+
+    def call(self, route: str, params: Optional[Dict[str, Any]] = None, options: Optional[CallOptions] = None) -> Union[Result, TextResult]:
+        """Runs any endpoint: apish.call("/reddit/v1/subreddit", {"subreddit": "python"})."""
+        o = options or {}
+        retries = o.get("max_retries", self.max_retries)
+        started = time.monotonic()
+        attempt = 0
+        while True:
+            try:
+                res = self._http.get(self.base_url + route, params=_query(params or {}, o), headers={"x-api-key": self._key, "accept": "application/json"}, timeout=o.get("timeout", self.timeout))
+            except httpx.TransportError:
+                if attempt >= retries:
+                    raise
+                time.sleep(_wait(None, attempt))
+                attempt += 1
+                continue
+            if res.is_success:
+                return _result(res, started)
+            err = _error(res)
+            if not err.retryable or attempt >= retries:
+                raise err
+            time.sleep(_wait(res, attempt))
+            attempt += 1
+
+    def paginate(self, route: str, params: Optional[Dict[str, Any]] = None, options: Optional[CallOptions] = None, *, max_pages: Optional[int] = None) -> Iterator[Union[Result, TextResult]]:
+        """Every page of a paginated endpoint: for page in apish.paginate("/reddit/v1/subreddit", {"subreddit": "python"}, max_pages=5)."""
+        rule = PAGINATION.get(route)
+        p = dict(params or {})
+        n = 0
+        while max_pages is None or n < max_pages:
+            page = self.call(route, p, options)
+            yield page
+            n += 1
+            nxt = page.get(rule[0]) if rule and isinstance(page, dict) else None
+            if nxt in (None, "", False):
+                return
+            p[rule[1]] = nxt  # type: ignore[index]
+
+    @staticmethod
+    def credits(route: str) -> Optional[int]:
+        """Credits per successful call for a route, as of this SDK version."""
+        return CREDITS.get(route)
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> "Apish":
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.close()
+
+
+class AsyncApish(AsyncPlatforms):
+    """The api.sh client for asyncio: `await apish.tiktok.profile(username="nasa")`."""
+
+    def __init__(self, api_key: Optional[str] = None, *, base_url: str = DEFAULT_BASE_URL, timeout: float = 120.0, max_retries: int = 2, http_client: Optional[httpx.AsyncClient] = None) -> None:
+        self._key = _key(api_key)
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self._http = http_client or httpx.AsyncClient(timeout=timeout, headers={"user-agent": f"apish-python/{__version__}"})
+        super().__init__(self.call)
+        self.account = _AsyncAccount(self.call)
+
+    async def call(self, route: str, params: Optional[Dict[str, Any]] = None, options: Optional[CallOptions] = None) -> Union[Result, TextResult]:
+        o = options or {}
+        retries = o.get("max_retries", self.max_retries)
+        started = time.monotonic()
+        attempt = 0
+        while True:
+            try:
+                res = await self._http.get(self.base_url + route, params=_query(params or {}, o), headers={"x-api-key": self._key, "accept": "application/json"}, timeout=o.get("timeout", self.timeout))
+            except httpx.TransportError:
+                if attempt >= retries:
+                    raise
+                await asyncio.sleep(_wait(None, attempt))
+                attempt += 1
+                continue
+            if res.is_success:
+                return _result(res, started)
+            err = _error(res)
+            if not err.retryable or attempt >= retries:
+                raise err
+            await asyncio.sleep(_wait(res, attempt))
+            attempt += 1
+
+    async def paginate(self, route: str, params: Optional[Dict[str, Any]] = None, options: Optional[CallOptions] = None, *, max_pages: Optional[int] = None) -> AsyncIterator[Union[Result, TextResult]]:
+        rule = PAGINATION.get(route)
+        p = dict(params or {})
+        n = 0
+        while max_pages is None or n < max_pages:
+            page = await self.call(route, p, options)
+            yield page
+            n += 1
+            nxt = page.get(rule[0]) if rule and isinstance(page, dict) else None
+            if nxt in (None, "", False):
+                return
+            p[rule[1]] = nxt  # type: ignore[index]
+
+    async def aclose(self) -> None:
+        await self._http.aclose()
+
+    async def __aenter__(self) -> "AsyncApish":
+        return self
+
+    async def __aexit__(self, *exc: Any) -> None:
+        await self.aclose()
+
+
+class _Account:
+    """Your balance, usage, logs and past responses. Free (no credits)."""
+
+    def __init__(self, call: Any) -> None:
+        self._call = call
+
+    def get(self) -> Result:
+        """Credits by bucket, plan, spend today / this month (UTC) and spend limits."""
+        return self._call("/v1/account", {})
+
+    def usage(self, days: int = 30) -> Result:
+        """Calls, errors and credits per UTC day (1-90 days) and the top endpoints."""
+        return self._call("/v1/account/usage", {"days": days})
+
+    def logs(self, *, limit: int = 50, status: Optional[str] = None, route: Optional[str] = None, key: Optional[str] = None, since: Optional[str] = None, before: Optional[str] = None) -> Result:
+        """Calls of the last 30 days, newest first; next page with before=result["next"]."""
+        return self._call("/v1/account/logs", {"limit": limit, "status": status, "route": route, "key": key, "since": since, "before": before})
+
+    def result(self, request_id: str, *, output: Optional[str] = None) -> Union[Result, TextResult]:
+        """The response of an earlier call (its x-request-id) again, free, for 30 days."""
+        return self._call(f"/v1/results/{quote(request_id)}", {}, {"output": output} if output else None)
+
+
+class _AsyncAccount:
+    """Your balance, usage, logs and past responses. Free (no credits)."""
+
+    def __init__(self, call: Any) -> None:
+        self._call = call
+
+    async def get(self) -> Result:
+        return await self._call("/v1/account", {})
+
+    async def usage(self, days: int = 30) -> Result:
+        return await self._call("/v1/account/usage", {"days": days})
+
+    async def logs(self, *, limit: int = 50, status: Optional[str] = None, route: Optional[str] = None, key: Optional[str] = None, since: Optional[str] = None, before: Optional[str] = None) -> Result:
+        return await self._call("/v1/account/logs", {"limit": limit, "status": status, "route": route, "key": key, "since": since, "before": before})
+
+    async def result(self, request_id: str, *, output: Optional[str] = None) -> Union[Result, TextResult]:
+        return await self._call(f"/v1/results/{quote(request_id)}", {}, {"output": output} if output else None)