beachdayapi 0.1.0__tar.gz

beachdayapi-0.1.0/PKG-INFO

@@ -0,0 +1,122 @@
+Metadata-Version: 2.4
+Name: beachdayapi
+Version: 0.1.0
+Summary: Python client for the Beach Day API — real-time beach and surf conditions
+Author-email: Beach Day API <hello@beachdayapi.com>
+License: MIT
+Project-URL: Homepage, https://beachdayapi.com
+Project-URL: Documentation, https://beachdayapi.com/docs
+Project-URL: Repository, https://github.com/rv888/beachdayapi
+Project-URL: Issues, https://github.com/rv888/beachdayapi/issues
+Keywords: beach,surf,water-quality,weather,api
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
+Classifier: Topic :: Internet :: WWW/HTTP
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# Beach Day API — Python Client
+
+[![PyPI version](https://img.shields.io/pypi/v/beachdayapi.svg)](https://pypi.org/project/beachdayapi/)
+[![Python](https://img.shields.io/pypi/pyversions/beachdayapi.svg)](https://pypi.org/project/beachdayapi/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Python client for the [Beach Day API](https://beachdayapi.com) — water quality, weather, tides, ocean conditions, beach rules, amenities, and composite scoring in a single call. Covers 1,900+ beaches across the US and Australia.
+
+```bash
+pip install beachdayapi
+```
+
+## Quick Start
+
+```python
+from beachdayapi import BeachDayAPI
+
+client = BeachDayAPI("bda_your_api_key")
+
+# Search beaches in California
+beaches = client.beaches.list(state="CA")
+for b in beaches["data"]:
+    print(b["name"], b["state"])
+
+# Get full detail for a beach
+beach = client.beaches.get(372)
+print(beach["data"]["name"], beach["data"]["beach_day_score"])
+
+# Get current conditions
+conditions = client.beaches.conditions(372)
+print(conditions["data"]["water_quality_grade"])
+
+# Get top-scored beaches
+scored = client.beaches.scored(min_score=70, limit=10)
+for b in scored["data"]:
+    print(f"{b['name']}: {b['beach_day_score']}")
+
+# Health check (no API key needed)
+health = client.health()
+print(health)
+```
+
+## API Key
+
+Sign up at [beachdayapi.com](https://beachdayapi.com) to get your free API key (50 free credits, no credit card). Your key starts with `bda_`.
+
+You can also set the `BEACHDAY_API_KEY` environment variable:
+
+```python
+import os
+from beachdayapi import BeachDayAPI
+
+client = BeachDayAPI(os.environ["BEACHDAY_API_KEY"])
+```
+
+## Endpoints
+
+| Method | Endpoint | Cost | Description |
+|---|---|---|---|
+| `client.health()` | `GET /v1/health` | Free | API health check |
+| `client.beaches.list()` | `GET /v1/beaches` | 1 credit | Search beaches |
+| `client.beaches.get(id)` | `GET /v1/beaches/{id}` | 5 credits | Beach detail |
+| `client.beaches.conditions(id)` | `GET /v1/beaches/{id}/conditions` | 3 credits | Current conditions |
+| `client.beaches.scored()` | `GET /v1/beaches/scored` | 10 credits | Scored beaches |
+
+## Error Handling
+
+```python
+from beachdayapi import (
+    BeachDayAPI,
+    AuthenticationError,
+    InsufficientCreditsError,
+    NotFoundError,
+    RateLimitError,
+    ServerError,
+)
+
+client = BeachDayAPI("bda_invalid_key")
+
+try:
+    client.beaches.list(state="CA")
+except AuthenticationError:
+    print("Check your API key")
+except InsufficientCreditsError:
+    print("Buy more credits at beachdayapi.com/credits/pricing/")
+except RateLimitError:
+    print("Slow down")
+```
+
+## Requirements
+
+- Python 3.9+
+- Zero dependencies (stdlib only)
+
+## License
+
+MIT — see the main [Beach Day API repository](https://github.com/rv888/beachdayapi).

beachdayapi-0.1.0/README.md

@@ -0,0 +1,97 @@
+# Beach Day API — Python Client
+
+[![PyPI version](https://img.shields.io/pypi/v/beachdayapi.svg)](https://pypi.org/project/beachdayapi/)
+[![Python](https://img.shields.io/pypi/pyversions/beachdayapi.svg)](https://pypi.org/project/beachdayapi/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Python client for the [Beach Day API](https://beachdayapi.com) — water quality, weather, tides, ocean conditions, beach rules, amenities, and composite scoring in a single call. Covers 1,900+ beaches across the US and Australia.
+
+```bash
+pip install beachdayapi
+```
+
+## Quick Start
+
+```python
+from beachdayapi import BeachDayAPI
+
+client = BeachDayAPI("bda_your_api_key")
+
+# Search beaches in California
+beaches = client.beaches.list(state="CA")
+for b in beaches["data"]:
+    print(b["name"], b["state"])
+
+# Get full detail for a beach
+beach = client.beaches.get(372)
+print(beach["data"]["name"], beach["data"]["beach_day_score"])
+
+# Get current conditions
+conditions = client.beaches.conditions(372)
+print(conditions["data"]["water_quality_grade"])
+
+# Get top-scored beaches
+scored = client.beaches.scored(min_score=70, limit=10)
+for b in scored["data"]:
+    print(f"{b['name']}: {b['beach_day_score']}")
+
+# Health check (no API key needed)
+health = client.health()
+print(health)
+```
+
+## API Key
+
+Sign up at [beachdayapi.com](https://beachdayapi.com) to get your free API key (50 free credits, no credit card). Your key starts with `bda_`.
+
+You can also set the `BEACHDAY_API_KEY` environment variable:
+
+```python
+import os
+from beachdayapi import BeachDayAPI
+
+client = BeachDayAPI(os.environ["BEACHDAY_API_KEY"])
+```
+
+## Endpoints
+
+| Method | Endpoint | Cost | Description |
+|---|---|---|---|
+| `client.health()` | `GET /v1/health` | Free | API health check |
+| `client.beaches.list()` | `GET /v1/beaches` | 1 credit | Search beaches |
+| `client.beaches.get(id)` | `GET /v1/beaches/{id}` | 5 credits | Beach detail |
+| `client.beaches.conditions(id)` | `GET /v1/beaches/{id}/conditions` | 3 credits | Current conditions |
+| `client.beaches.scored()` | `GET /v1/beaches/scored` | 10 credits | Scored beaches |
+
+## Error Handling
+
+```python
+from beachdayapi import (
+    BeachDayAPI,
+    AuthenticationError,
+    InsufficientCreditsError,
+    NotFoundError,
+    RateLimitError,
+    ServerError,
+)
+
+client = BeachDayAPI("bda_invalid_key")
+
+try:
+    client.beaches.list(state="CA")
+except AuthenticationError:
+    print("Check your API key")
+except InsufficientCreditsError:
+    print("Buy more credits at beachdayapi.com/credits/pricing/")
+except RateLimitError:
+    print("Slow down")
+```
+
+## Requirements
+
+- Python 3.9+
+- Zero dependencies (stdlib only)
+
+## License
+
+MIT — see the main [Beach Day API repository](https://github.com/rv888/beachdayapi).

beachdayapi-0.1.0/beachdayapi/__init__.py

@@ -0,0 +1,29 @@
+"""Beach Day API Python Client
+
+A lightweight Python client for the Beach Day API.
+
+    pip install beachdayapi
+
+Usage:
+    from beachdayapi import BeachDayAPI
+
+    client = BeachDayAPI("bda_your_api_key")
+
+    # Search beaches
+    beaches = client.beaches.list(state="CA")
+
+    # Get beach detail
+    beach = client.beaches.get(372)
+
+    # Get scored beaches
+    scored = client.beaches.scored(min_score=70)
+
+    # Health check (no auth)
+    health = client.health()
+"""
+
+from .client import BeachDayAPI
+from .exceptions import BeachDayAPIError, AuthenticationError, InsufficientCreditsError
+
+__all__ = ["BeachDayAPI", "BeachDayAPIError", "AuthenticationError", "InsufficientCreditsError"]
+__version__ = "0.1.0"

beachdayapi-0.1.0/beachdayapi/client.py

@@ -0,0 +1,157 @@
+import urllib.request
+import urllib.error
+import urllib.parse
+import json
+from typing import Optional, Dict, Any, List
+from .exceptions import (
+    AuthenticationError,
+    InsufficientCreditsError,
+    NotFoundError,
+    RateLimitError,
+    ServerError,
+    BeachDayAPIError,
+)
+
+
+class BeachDayAPI:
+    """Client for the Beach Day API.
+
+    Args:
+        api_key: Your Beach Day API key (starts with 'bda_').
+        base_url: Override the API base URL. Defaults to production.
+        timeout: Request timeout in seconds. Default 30.
+    """
+
+    BASE_URL = "https://beachdayapi.com/v1"
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        timeout: int = 30,
+    ):
+        self.api_key = api_key
+        self.base_url = base_url or self.BASE_URL
+        self.timeout = timeout
+        self.beaches = BeachEndpoints(self)
+        self.health = lambda: self._get("/health", auth_required=False)
+
+    def _auth_headers(self) -> Dict[str, str]:
+        return {"Authorization": f"Bearer {self.api_key}"}
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        params: Optional[Dict[str, Any]] = None,
+        auth_required: bool = True,
+    ) -> Dict[str, Any]:
+        url = f"{self.base_url}{path}"
+        headers = {"Accept": "application/json", "User-Agent": "beachdayapi-python/0.1.0"}
+        if auth_required:
+            if not self.api_key:
+                raise AuthenticationError(
+                    "API key required. Pass api_key='bda_...' to BeachDayAPI(), "
+                    "or set BEACHDAY_API_KEY environment variable."
+                )
+            headers.update(self._auth_headers())
+
+        if params:
+            filtered = {k: v for k, v in params.items() if v is not None}
+            if filtered:
+                url = f"{url}?{urllib.parse.urlencode(filtered)}"
+
+        req = urllib.request.Request(url, method=method, headers=headers)
+
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout) as resp:
+                return json.loads(resp.read().decode("utf-8"))
+        except urllib.error.HTTPError as e:
+            body = {}
+            try:
+                body = json.loads(e.read().decode("utf-8"))
+            except Exception:
+                pass
+            self._raise_error(e.code, body)
+            return {}  # unreachable, satisfies type checker
+        except urllib.error.URLError as e:
+            raise BeachDayAPIError(f"Connection error: {e.reason}") from e
+
+    def _get(
+        self, path: str, params=None, auth_required=True
+    ) -> Dict[str, Any]:
+        return self._request("GET", path, params, auth_required)
+
+    @staticmethod
+    def _raise_error(status: int, body: dict):
+        detail = body.get("detail") or body.get("message", "")
+        if status == 401:
+            raise AuthenticationError(detail or "Invalid or missing API key.")
+        if status == 402:
+            required = body.get("required", "?")
+            balance = body.get("balance", "?")
+            msg = f"Insufficient credits. Need {required}, have {balance}."
+            raise InsufficientCreditsError(msg)
+        if status == 404:
+            raise NotFoundError(detail or "Resource not found.")
+        if status == 429:
+            raise RateLimitError(detail or "Too many requests.")
+        if 500 <= status < 600:
+            raise ServerError(detail or f"Server error (HTTP {status}).")
+        raise BeachDayAPIError(f"HTTP {status}: {detail or 'Unknown error'}")
+
+
+class BeachEndpoints:
+    """Access beach-related endpoints."""
+
+    def __init__(self, client: BeachDayAPI):
+        self._client = client
+
+    def list(
+        self,
+        state: Optional[str] = None,
+        search: Optional[str] = None,
+        limit: Optional[int] = None,
+        offset: Optional[int] = None,
+    ) -> Dict[str, Any]:
+        """List beaches with optional filters.
+
+        Args:
+            state: Two-letter US state code or 'AU-NSW'/'AU-VIC'.
+            search: Search term for beach name.
+            limit: Max results per page.
+            offset: Pagination offset.
+        """
+        return self._client._get("/beaches", {
+            "state": state,
+            "search": search,
+            "limit": limit,
+            "offset": offset,
+        })
+
+    def get(self, beach_id: int) -> Dict[str, Any]:
+        """Get full detail for a single beach."""
+        return self._client._get(f"/beaches/{beach_id}")
+
+    def conditions(self, beach_id: int) -> Dict[str, Any]:
+        """Get current conditions for a beach."""
+        return self._client._get(f"/beaches/{beach_id}/conditions")
+
+    def scored(
+        self,
+        state: Optional[str] = None,
+        min_score: Optional[int] = None,
+        limit: Optional[int] = None,
+    ) -> Dict[str, Any]:
+        """Get beaches with composite Beach Day Scores.
+
+        Args:
+            state: Filter by state code.
+            min_score: Minimum score threshold (0-100).
+            limit: Max results.
+        """
+        return self._client._get("/beaches/scored", {
+            "state": state,
+            "min_score": min_score,
+            "limit": limit,
+        })

beachdayapi-0.1.0/beachdayapi/exceptions.py

@@ -0,0 +1,28 @@
+class BeachDayAPIError(Exception):
+    """Base exception for Beach Day API errors."""
+    pass
+
+
+class AuthenticationError(BeachDayAPIError):
+    """Invalid or missing API key (HTTP 401)."""
+    pass
+
+
+class InsufficientCreditsError(BeachDayAPIError):
+    """Not enough credits for the request (HTTP 402)."""
+    pass
+
+
+class NotFoundError(BeachDayAPIError):
+    """Resource not found (HTTP 404)."""
+    pass
+
+
+class RateLimitError(BeachDayAPIError):
+    """Rate limit exceeded (HTTP 429)."""
+    pass
+
+
+class ServerError(BeachDayAPIError):
+    """Server-side error (HTTP 5xx)."""
+    pass

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

@@ -0,0 +1,122 @@
+Metadata-Version: 2.4
+Name: beachdayapi
+Version: 0.1.0
+Summary: Python client for the Beach Day API — real-time beach and surf conditions
+Author-email: Beach Day API <hello@beachdayapi.com>
+License: MIT
+Project-URL: Homepage, https://beachdayapi.com
+Project-URL: Documentation, https://beachdayapi.com/docs
+Project-URL: Repository, https://github.com/rv888/beachdayapi
+Project-URL: Issues, https://github.com/rv888/beachdayapi/issues
+Keywords: beach,surf,water-quality,weather,api
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
+Classifier: Topic :: Internet :: WWW/HTTP
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# Beach Day API — Python Client
+
+[![PyPI version](https://img.shields.io/pypi/v/beachdayapi.svg)](https://pypi.org/project/beachdayapi/)
+[![Python](https://img.shields.io/pypi/pyversions/beachdayapi.svg)](https://pypi.org/project/beachdayapi/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Python client for the [Beach Day API](https://beachdayapi.com) — water quality, weather, tides, ocean conditions, beach rules, amenities, and composite scoring in a single call. Covers 1,900+ beaches across the US and Australia.
+
+```bash
+pip install beachdayapi
+```
+
+## Quick Start
+
+```python
+from beachdayapi import BeachDayAPI
+
+client = BeachDayAPI("bda_your_api_key")
+
+# Search beaches in California
+beaches = client.beaches.list(state="CA")
+for b in beaches["data"]:
+    print(b["name"], b["state"])
+
+# Get full detail for a beach
+beach = client.beaches.get(372)
+print(beach["data"]["name"], beach["data"]["beach_day_score"])
+
+# Get current conditions
+conditions = client.beaches.conditions(372)
+print(conditions["data"]["water_quality_grade"])
+
+# Get top-scored beaches
+scored = client.beaches.scored(min_score=70, limit=10)
+for b in scored["data"]:
+    print(f"{b['name']}: {b['beach_day_score']}")
+
+# Health check (no API key needed)
+health = client.health()
+print(health)
+```
+
+## API Key
+
+Sign up at [beachdayapi.com](https://beachdayapi.com) to get your free API key (50 free credits, no credit card). Your key starts with `bda_`.
+
+You can also set the `BEACHDAY_API_KEY` environment variable:
+
+```python
+import os
+from beachdayapi import BeachDayAPI
+
+client = BeachDayAPI(os.environ["BEACHDAY_API_KEY"])
+```
+
+## Endpoints
+
+| Method | Endpoint | Cost | Description |
+|---|---|---|---|
+| `client.health()` | `GET /v1/health` | Free | API health check |
+| `client.beaches.list()` | `GET /v1/beaches` | 1 credit | Search beaches |
+| `client.beaches.get(id)` | `GET /v1/beaches/{id}` | 5 credits | Beach detail |
+| `client.beaches.conditions(id)` | `GET /v1/beaches/{id}/conditions` | 3 credits | Current conditions |
+| `client.beaches.scored()` | `GET /v1/beaches/scored` | 10 credits | Scored beaches |
+
+## Error Handling
+
+```python
+from beachdayapi import (
+    BeachDayAPI,
+    AuthenticationError,
+    InsufficientCreditsError,
+    NotFoundError,
+    RateLimitError,
+    ServerError,
+)
+
+client = BeachDayAPI("bda_invalid_key")
+
+try:
+    client.beaches.list(state="CA")
+except AuthenticationError:
+    print("Check your API key")
+except InsufficientCreditsError:
+    print("Buy more credits at beachdayapi.com/credits/pricing/")
+except RateLimitError:
+    print("Slow down")
+```
+
+## Requirements
+
+- Python 3.9+
+- Zero dependencies (stdlib only)
+
+## License
+
+MIT — see the main [Beach Day API repository](https://github.com/rv888/beachdayapi).

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

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

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

@@ -0,0 +1 @@
+

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

@@ -0,0 +1 @@
+beachdayapi

beachdayapi-0.1.0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["setuptools>=64", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "beachdayapi"
+version = "0.1.0"
+description = "Python client for the Beach Day API — real-time beach and surf conditions"
+readme = "README.md"
+license = {text = "MIT"}
+authors = [{name = "Beach Day API", email = "hello@beachdayapi.com"}]
+keywords = ["beach", "surf", "water-quality", "weather", "api"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Atmospheric Science",
+    "Topic :: Internet :: WWW/HTTP",
+]
+requires-python = ">=3.9"
+dependencies = []
+
+[project.urls]
+Homepage = "https://beachdayapi.com"
+Documentation = "https://beachdayapi.com/docs"
+Repository = "https://github.com/rv888/beachdayapi"
+Issues = "https://github.com/rv888/beachdayapi/issues"
+
+[tool.setuptools]
+packages = ["beachdayapi"]

beachdayapi-0.1.0/setup.cfg

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