website-traffic-database 0.1.0__tar.gz

website_traffic_database-0.1.0/LICENSE

@@ -0,0 +1,5 @@
+MIT License
+
+Copyright (c) 2026 ApiVault Labs
+
+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. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND.

website_traffic_database-0.1.0/PKG-INFO

@@ -0,0 +1,101 @@
+Metadata-Version: 2.4
+Name: website-traffic-database
+Version: 0.1.0
+Summary: Python SDK for Website Traffic Database on Apify. Find and compare websites by traffic, country, category and growth signals through the hosted Apify Actor.
+Author: ApiVault Labs
+License: MIT
+Project-URL: Homepage, https://github.com/apivault-labs/website-traffic-database-python
+Project-URL: Documentation, https://github.com/apivault-labs/website-traffic-database-python#readme
+Project-URL: Apify Actor, https://apify.com/apivault_labs/website-traffic-database
+Project-URL: Bug Tracker, https://github.com/apivault-labs/website-traffic-database-python/issues
+Keywords: website-traffic,traffic-database,competitive-intelligence,lead-generation,market-research,apify,python-sdk
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.31.0
+Dynamic: license-file
+
+# Website Traffic Database — Python SDK
+
+Python client for the [Website Traffic Database Apify Actor](https://apify.com/apivault_labs/website-traffic-database). Send public Actor inputs, wait for the hosted run, and receive clean Dataset rows without maintaining scraping infrastructure.
+
+[![Apify Actor](https://img.shields.io/badge/Apify-Actor-blue)](https://apify.com/apivault_labs/website-traffic-database)
+[![Python 3.9+](https://img.shields.io/badge/Python-3.9%2B-blue)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
+## Results
+
+- Traffic and rank filters
+- Country and category discovery
+- Growth and engagement signals
+- Direct domain and similar-site workflows
+
+Traffic values are estimates. The wrapper exposes only the Actor's public contract; processing remains inside the hosted Actor.
+
+## Install
+
+```bash
+pip install git+https://github.com/apivault-labs/website-traffic-database-python.git
+```
+
+Create an Apify token at [Console → Integrations](https://console.apify.com/account/integrations), then:
+
+```python
+from website_traffic_database import WebsiteTrafficDatabaseClient
+
+client = WebsiteTrafficDatabaseClient(api_token="apify_api_xxxxxx")
+rows = client.run({'workflow': 'auto',
+ 'country': 'US',
+ 'minVisits': 10000,
+ 'onlyGrowing': True,
+ 'maxResults': 100})
+print(rows[0] if rows else "No results")
+```
+
+You can set `APIFY_API_TOKEN` instead of passing the token in code.
+
+## Public input options
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `workflow` | `string` | `auto` | Discover websites, inspect domains or find similar sites. |
+| `minVisits` | `integer` | `0` | Minimum estimated monthly visits. |
+| `maxVisits` | `integer` | `0` | Optional maximum estimated monthly visits. |
+| `category` | `string` | `` | Website category filter. |
+| `country` | `string` | `` | ISO-2 country code. |
+| `hasAiTraffic` | `boolean` | `False` | Keep sites with detected AI referral traffic. |
+| `onlyGrowing` | `boolean` | `False` | Keep sites with positive traffic growth. |
+| `minGrowthPercent` | `number` | `0` | Minimum growth percentage. |
+| `keyword` | `string` | `` | Match a domain or site name. |
+| `trafficSource` | `string` | `` | Traffic source to filter by. |
+| `maxBounce` | `number` | `0` | Optional maximum bounce rate. |
+| `minPagesPerVisit` | `number` | `0` | Minimum pages per visit. |
+| `maxResults` | `integer` | `100` | Maximum number of returned rows. |
+| `sortBy` | `string` | `visits` | Public field used to order results. |
+| `sortOrder` | `string` | `desc` | Ascending or descending order. |
+| `outputPreset` | `string` | `outreach` | Choose a public result layout. |
+| `domains` | `array` | `[]` | Domains to inspect directly. |
+| `similarTo` | `string` | `` | Domain used to discover similar websites. |
+
+The complete, versioned schema is also available on the [Actor page](https://apify.com/apivault_labs/website-traffic-database).
+
+## Pricing
+
+Pay per delivered result through Apify, starting around **$7/1,000 results** on paid tiers. Free-plan pricing and platform usage can differ; check the Actor page before large runs.
+
+## Examples
+
+- `examples/quickstart.py` — first run
+- `examples/bulk_analysis.py` — expand a target list
+- `examples/export_csv.py` — save flat result fields
+- `examples/save_json.py` — preserve nested output
+- `examples/cost_estimate.py` — estimate result-event charges
+- `examples/environment_token.py` — keep credentials out of code
+
+## Architecture and privacy
+
+This repository is intentionally a thin API client. Collection, retries, analysis and billing run inside the hosted Apify Actor. No private implementation, credentials, scoring weights or infrastructure configuration are included.
+
+## License
+
+MIT. The hosted Actor is a separate paid service governed by Apify terms.

website_traffic_database-0.1.0/README.md

@@ -0,0 +1,84 @@
+# Website Traffic Database — Python SDK
+
+Python client for the [Website Traffic Database Apify Actor](https://apify.com/apivault_labs/website-traffic-database). Send public Actor inputs, wait for the hosted run, and receive clean Dataset rows without maintaining scraping infrastructure.
+
+[![Apify Actor](https://img.shields.io/badge/Apify-Actor-blue)](https://apify.com/apivault_labs/website-traffic-database)
+[![Python 3.9+](https://img.shields.io/badge/Python-3.9%2B-blue)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
+## Results
+
+- Traffic and rank filters
+- Country and category discovery
+- Growth and engagement signals
+- Direct domain and similar-site workflows
+
+Traffic values are estimates. The wrapper exposes only the Actor's public contract; processing remains inside the hosted Actor.
+
+## Install
+
+```bash
+pip install git+https://github.com/apivault-labs/website-traffic-database-python.git
+```
+
+Create an Apify token at [Console → Integrations](https://console.apify.com/account/integrations), then:
+
+```python
+from website_traffic_database import WebsiteTrafficDatabaseClient
+
+client = WebsiteTrafficDatabaseClient(api_token="apify_api_xxxxxx")
+rows = client.run({'workflow': 'auto',
+ 'country': 'US',
+ 'minVisits': 10000,
+ 'onlyGrowing': True,
+ 'maxResults': 100})
+print(rows[0] if rows else "No results")
+```
+
+You can set `APIFY_API_TOKEN` instead of passing the token in code.
+
+## Public input options
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `workflow` | `string` | `auto` | Discover websites, inspect domains or find similar sites. |
+| `minVisits` | `integer` | `0` | Minimum estimated monthly visits. |
+| `maxVisits` | `integer` | `0` | Optional maximum estimated monthly visits. |
+| `category` | `string` | `` | Website category filter. |
+| `country` | `string` | `` | ISO-2 country code. |
+| `hasAiTraffic` | `boolean` | `False` | Keep sites with detected AI referral traffic. |
+| `onlyGrowing` | `boolean` | `False` | Keep sites with positive traffic growth. |
+| `minGrowthPercent` | `number` | `0` | Minimum growth percentage. |
+| `keyword` | `string` | `` | Match a domain or site name. |
+| `trafficSource` | `string` | `` | Traffic source to filter by. |
+| `maxBounce` | `number` | `0` | Optional maximum bounce rate. |
+| `minPagesPerVisit` | `number` | `0` | Minimum pages per visit. |
+| `maxResults` | `integer` | `100` | Maximum number of returned rows. |
+| `sortBy` | `string` | `visits` | Public field used to order results. |
+| `sortOrder` | `string` | `desc` | Ascending or descending order. |
+| `outputPreset` | `string` | `outreach` | Choose a public result layout. |
+| `domains` | `array` | `[]` | Domains to inspect directly. |
+| `similarTo` | `string` | `` | Domain used to discover similar websites. |
+
+The complete, versioned schema is also available on the [Actor page](https://apify.com/apivault_labs/website-traffic-database).
+
+## Pricing
+
+Pay per delivered result through Apify, starting around **$7/1,000 results** on paid tiers. Free-plan pricing and platform usage can differ; check the Actor page before large runs.
+
+## Examples
+
+- `examples/quickstart.py` — first run
+- `examples/bulk_analysis.py` — expand a target list
+- `examples/export_csv.py` — save flat result fields
+- `examples/save_json.py` — preserve nested output
+- `examples/cost_estimate.py` — estimate result-event charges
+- `examples/environment_token.py` — keep credentials out of code
+
+## Architecture and privacy
+
+This repository is intentionally a thin API client. Collection, retries, analysis and billing run inside the hosted Apify Actor. No private implementation, credentials, scoring weights or infrastructure configuration are included.
+
+## License
+
+MIT. The hosted Actor is a separate paid service governed by Apify terms.

website_traffic_database-0.1.0/pyproject.toml

@@ -0,0 +1,23 @@
+[build-system]
+requires = ["setuptools>=64", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "website-traffic-database"
+version = "0.1.0"
+description = "Python SDK for Website Traffic Database on Apify. Find and compare websites by traffic, country, category and growth signals through the hosted Apify Actor."
+readme = "README.md"
+license = { text = "MIT" }
+authors = [{ name = "ApiVault Labs" }]
+requires-python = ">=3.9"
+dependencies = ["requests>=2.31.0"]
+keywords = ["website-traffic", "traffic-database", "competitive-intelligence", "lead-generation", "market-research", "apify", "python-sdk"]
+
+[project.urls]
+Homepage = "https://github.com/apivault-labs/website-traffic-database-python"
+Documentation = "https://github.com/apivault-labs/website-traffic-database-python#readme"
+"Apify Actor" = "https://apify.com/apivault_labs/website-traffic-database"
+"Bug Tracker" = "https://github.com/apivault-labs/website-traffic-database-python/issues"
+
+[tool.setuptools.packages.find]
+include = ["website_traffic_database*"]

website_traffic_database-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

website_traffic_database-0.1.0/website_traffic_database/__init__.py

@@ -0,0 +1,6 @@
+"""Python SDK for the hosted Website Traffic Database Apify Actor."""
+from .client import WebsiteTrafficDatabaseClient
+from .exceptions import WebsiteTrafficDatabaseError, AuthenticationError, ActorRunError, ActorTimeoutError
+
+__version__ = "0.1.0"
+__all__ = ["WebsiteTrafficDatabaseClient", "WebsiteTrafficDatabaseError", "AuthenticationError", "ActorRunError", "ActorTimeoutError"]

website_traffic_database-0.1.0/website_traffic_database/client.py

@@ -0,0 +1,112 @@
+"""Thin synchronous client for the Website Traffic Database Apify Actor."""
+from __future__ import annotations
+
+import os
+import time
+from typing import Any, Mapping
+
+import requests
+
+from .exceptions import ActorRunError, ActorTimeoutError, AuthenticationError, WebsiteTrafficDatabaseError
+
+ACTOR_ID = "apivault_labs~website-traffic-database"
+APIFY_API_BASE = "https://api.apify.com/v2"
+TERMINAL_FAIL = {"FAILED", "TIMED-OUT", "ABORTED"}
+
+
+class WebsiteTrafficDatabaseClient:
+    """Run the hosted Actor and download its Dataset results."""
+
+    def __init__(self, api_token: str | None = None, timeout: int = 600,
+                 poll_interval: float = 3.0):
+        token = api_token or os.environ.get("APIFY_API_TOKEN")
+        if not token:
+            raise AuthenticationError(
+                "Pass api_token or set APIFY_API_TOKEN. Create a token at "
+                "https://console.apify.com/account/integrations"
+            )
+        self.timeout = int(timeout)
+        self.poll_interval = float(poll_interval)
+        self.base_url = APIFY_API_BASE
+        self.session = requests.Session()
+        self.session.headers.update({
+            "Authorization": f"Bearer {token}",
+            "Content-Type": "application/json",
+            "User-Agent": "website-traffic-database-python/0.1.0",
+        })
+
+    def run(self, actor_input: Mapping[str, Any], *, actor_timeout_secs: int = 300) -> list[dict[str, Any]]:
+        """Start one Actor run, wait for completion and return clean Dataset items."""
+        if not isinstance(actor_input, Mapping):
+            raise TypeError("actor_input must be a mapping")
+        run_id = self._start(dict(actor_input), actor_timeout_secs)
+        run = self._wait(run_id)
+        dataset_id = run.get("defaultDatasetId")
+        if not dataset_id:
+            raise ActorRunError("Successful run did not expose a Dataset ID")
+        return self._dataset(dataset_id)
+
+    def run_one(self, actor_input: Mapping[str, Any], **kwargs: Any) -> dict[str, Any]:
+        """Return the first Dataset row, raising when no result was produced."""
+        rows = self.run(actor_input, **kwargs)
+        if not rows:
+            raise ActorRunError("Actor completed but returned no Dataset rows")
+        return rows[0]
+
+    @staticmethod
+    def estimate_cost(result_count: int, price_per_1000: float = 7.0) -> float:
+        """Estimate result charges; actual tier pricing and platform usage may vary."""
+        if result_count < 0:
+            raise ValueError("result_count cannot be negative")
+        return round(result_count * price_per_1000 / 1000, 6)
+
+    def _start(self, payload: dict[str, Any], timeout_secs: int) -> str:
+        try:
+            response = self.session.post(
+                f"{self.base_url}/acts/{ACTOR_ID}/runs",
+                params={"timeout": int(timeout_secs)}, json=payload, timeout=30,
+            )
+        except requests.RequestException as exc:
+            raise WebsiteTrafficDatabaseError(f"Could not start Actor run: {exc}") from exc
+        if response.status_code == 401:
+            raise AuthenticationError("Apify rejected the API token")
+        if response.status_code >= 400:
+            raise ActorRunError(f"Run start failed with HTTP {response.status_code}: {response.text[:300]}")
+        run_id = (response.json().get("data") or {}).get("id")
+        if not run_id:
+            raise ActorRunError("Apify response did not contain a run ID")
+        return run_id
+
+    def _wait(self, run_id: str) -> dict[str, Any]:
+        deadline = time.monotonic() + self.timeout
+        while True:
+            try:
+                response = self.session.get(f"{self.base_url}/actor-runs/{run_id}", timeout=30)
+            except requests.RequestException as exc:
+                raise WebsiteTrafficDatabaseError(f"Could not poll Actor run: {exc}") from exc
+            if response.status_code >= 400:
+                raise ActorRunError(f"Run poll failed with HTTP {response.status_code}: {response.text[:300]}")
+            run = response.json().get("data") or {}
+            status = run.get("status")
+            if status == "SUCCEEDED":
+                return run
+            if status in TERMINAL_FAIL:
+                raise ActorRunError(f"Actor run ended with {status}: {run.get('statusMessage') or 'no details'}")
+            if time.monotonic() >= deadline:
+                raise ActorTimeoutError(f"Actor run {run_id} did not finish within {self.timeout} seconds")
+            time.sleep(self.poll_interval)
+
+    def _dataset(self, dataset_id: str) -> list[dict[str, Any]]:
+        try:
+            response = self.session.get(
+                f"{self.base_url}/datasets/{dataset_id}/items",
+                params={"clean": "true", "format": "json"}, timeout=120,
+            )
+        except requests.RequestException as exc:
+            raise WebsiteTrafficDatabaseError(f"Could not download Dataset: {exc}") from exc
+        if response.status_code >= 400:
+            raise ActorRunError(f"Dataset fetch failed with HTTP {response.status_code}: {response.text[:300]}")
+        data = response.json()
+        if not isinstance(data, list):
+            raise ActorRunError("Unexpected Dataset response type")
+        return data

website_traffic_database-0.1.0/website_traffic_database/exceptions.py

@@ -0,0 +1,13 @@
+"""Public exception hierarchy for the Website Traffic Database SDK."""
+
+class WebsiteTrafficDatabaseError(Exception):
+    """Base SDK error."""
+
+class AuthenticationError(WebsiteTrafficDatabaseError):
+    """The Apify token is missing or rejected."""
+
+class ActorRunError(WebsiteTrafficDatabaseError):
+    """The Actor run or Dataset request failed."""
+
+class ActorTimeoutError(WebsiteTrafficDatabaseError):
+    """The client stopped waiting before the Actor completed."""

website_traffic_database-0.1.0/website_traffic_database.egg-info/PKG-INFO

@@ -0,0 +1,101 @@
+Metadata-Version: 2.4
+Name: website-traffic-database
+Version: 0.1.0
+Summary: Python SDK for Website Traffic Database on Apify. Find and compare websites by traffic, country, category and growth signals through the hosted Apify Actor.
+Author: ApiVault Labs
+License: MIT
+Project-URL: Homepage, https://github.com/apivault-labs/website-traffic-database-python
+Project-URL: Documentation, https://github.com/apivault-labs/website-traffic-database-python#readme
+Project-URL: Apify Actor, https://apify.com/apivault_labs/website-traffic-database
+Project-URL: Bug Tracker, https://github.com/apivault-labs/website-traffic-database-python/issues
+Keywords: website-traffic,traffic-database,competitive-intelligence,lead-generation,market-research,apify,python-sdk
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.31.0
+Dynamic: license-file
+
+# Website Traffic Database — Python SDK
+
+Python client for the [Website Traffic Database Apify Actor](https://apify.com/apivault_labs/website-traffic-database). Send public Actor inputs, wait for the hosted run, and receive clean Dataset rows without maintaining scraping infrastructure.
+
+[![Apify Actor](https://img.shields.io/badge/Apify-Actor-blue)](https://apify.com/apivault_labs/website-traffic-database)
+[![Python 3.9+](https://img.shields.io/badge/Python-3.9%2B-blue)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
+## Results
+
+- Traffic and rank filters
+- Country and category discovery
+- Growth and engagement signals
+- Direct domain and similar-site workflows
+
+Traffic values are estimates. The wrapper exposes only the Actor's public contract; processing remains inside the hosted Actor.
+
+## Install
+
+```bash
+pip install git+https://github.com/apivault-labs/website-traffic-database-python.git
+```
+
+Create an Apify token at [Console → Integrations](https://console.apify.com/account/integrations), then:
+
+```python
+from website_traffic_database import WebsiteTrafficDatabaseClient
+
+client = WebsiteTrafficDatabaseClient(api_token="apify_api_xxxxxx")
+rows = client.run({'workflow': 'auto',
+ 'country': 'US',
+ 'minVisits': 10000,
+ 'onlyGrowing': True,
+ 'maxResults': 100})
+print(rows[0] if rows else "No results")
+```
+
+You can set `APIFY_API_TOKEN` instead of passing the token in code.
+
+## Public input options
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `workflow` | `string` | `auto` | Discover websites, inspect domains or find similar sites. |
+| `minVisits` | `integer` | `0` | Minimum estimated monthly visits. |
+| `maxVisits` | `integer` | `0` | Optional maximum estimated monthly visits. |
+| `category` | `string` | `` | Website category filter. |
+| `country` | `string` | `` | ISO-2 country code. |
+| `hasAiTraffic` | `boolean` | `False` | Keep sites with detected AI referral traffic. |
+| `onlyGrowing` | `boolean` | `False` | Keep sites with positive traffic growth. |
+| `minGrowthPercent` | `number` | `0` | Minimum growth percentage. |
+| `keyword` | `string` | `` | Match a domain or site name. |
+| `trafficSource` | `string` | `` | Traffic source to filter by. |
+| `maxBounce` | `number` | `0` | Optional maximum bounce rate. |
+| `minPagesPerVisit` | `number` | `0` | Minimum pages per visit. |
+| `maxResults` | `integer` | `100` | Maximum number of returned rows. |
+| `sortBy` | `string` | `visits` | Public field used to order results. |
+| `sortOrder` | `string` | `desc` | Ascending or descending order. |
+| `outputPreset` | `string` | `outreach` | Choose a public result layout. |
+| `domains` | `array` | `[]` | Domains to inspect directly. |
+| `similarTo` | `string` | `` | Domain used to discover similar websites. |
+
+The complete, versioned schema is also available on the [Actor page](https://apify.com/apivault_labs/website-traffic-database).
+
+## Pricing
+
+Pay per delivered result through Apify, starting around **$7/1,000 results** on paid tiers. Free-plan pricing and platform usage can differ; check the Actor page before large runs.
+
+## Examples
+
+- `examples/quickstart.py` — first run
+- `examples/bulk_analysis.py` — expand a target list
+- `examples/export_csv.py` — save flat result fields
+- `examples/save_json.py` — preserve nested output
+- `examples/cost_estimate.py` — estimate result-event charges
+- `examples/environment_token.py` — keep credentials out of code
+
+## Architecture and privacy
+
+This repository is intentionally a thin API client. Collection, retries, analysis and billing run inside the hosted Apify Actor. No private implementation, credentials, scoring weights or infrastructure configuration are included.
+
+## License
+
+MIT. The hosted Actor is a separate paid service governed by Apify terms.

website_traffic_database-0.1.0/website_traffic_database.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+LICENSE
+README.md
+pyproject.toml
+website_traffic_database/__init__.py
+website_traffic_database/client.py
+website_traffic_database/exceptions.py
+website_traffic_database.egg-info/PKG-INFO
+website_traffic_database.egg-info/SOURCES.txt
+website_traffic_database.egg-info/dependency_links.txt
+website_traffic_database.egg-info/requires.txt
+website_traffic_database.egg-info/top_level.txt

website_traffic_database-0.1.0/website_traffic_database.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

website_traffic_database-0.1.0/website_traffic_database.egg-info/requires.txt

@@ -0,0 +1 @@
+requests>=2.31.0

website_traffic_database-0.1.0/website_traffic_database.egg-info/top_level.txt

@@ -0,0 +1 @@
+website_traffic_database