Magicseaweed APImagicseaweed.com ↗

"""
Surfline API Scraper - Access global surf reports, forecasts, and spot data.
Get your API key from: https://parse.bot/settings
"""

import os
import requests
from datetime import datetime
from typing import Any, Optional


class ParseClient:
    """Client for Surfline API Scraper via Parse API."""
    
    def __init__(self, api_key: Optional[str] = None):
        """Initialize the Parse client with API credentials."""
        self.base_url = "https://api.parse.bot"
        self.scraper_id = "bdd16c83-771c-411b-b9e9-b7de50f4ec1a"
        self.api_key = api_key or os.getenv("PARSE_API_KEY")
        
        if not self.api_key:
            raise ValueError("API key must be provided or set in PARSE_API_KEY environment variable")
    
    def _call(self, endpoint: str, method: str = "POST", **params) -> dict[str, Any]:
        """Make API call to the Parse scraper endpoint."""
        url = f"{self.base_url}/scraper/{self.scraper_id}/{endpoint}"
        headers = {
            "X-API-Key": self.api_key,
            "Content-Type": "application/json"
        }
        
        if method.upper() == "GET":
            response = requests.get(url, headers=headers, params=params)
        elif method.upper() == "POST":
            response = requests.post(url, headers=headers, json=params)
        else:
            raise ValueError(f"Unsupported HTTP method: {method}")
        
        response.raise_for_status()
        return response.json()
    
    def search_spots(self, query: str) -> dict[str, Any]:
        """
        Search for surf spots by name.
        
        Args:
            query: The name of the beach or surf spot (e.g., 'Malibu', 'Pipeline')
        
        Returns:
            Dictionary containing search results with spot IDs and details
        """
        return self._call("search_spots", method="GET", query=query)
    
    def get_spot_forecast(self, spot_id: str, days: int = 5) -> dict[str, Any]:
        """
        Retrieve detailed surf forecast for a specific spot.
        
        Args:
            spot_id: The unique Surfline spot ID (found via search_spots)
            days: Number of days to forecast (1-16, default: 5)
        
        Returns:
            Dictionary containing wave, wind, tides, and weather forecast data
        """
        return self._call("get_spot_forecast", method="GET", spot_id=spot_id, days=days)
    
    def get_popular_spots(self) -> dict[str, Any]:
        """
        Retrieve a list of popular surf spots in the US.
        
        Returns:
            Dictionary containing array of popular spots with current conditions
        """
        return self._call("get_popular_spots", method="GET")


def format_timestamp(timestamp: int, utc_offset: int = 0) -> str:
    """Convert Unix timestamp to readable date/time."""
    return datetime.fromtimestamp(timestamp).strftime("%Y-%m-%d %H:%M:%S")


def print_wave_conditions(wave_data: dict[str, Any]) -> str:
    """Format wave condition data into a readable string."""
    surf = wave_data.get("surf", {})
    min_height = surf.get("min", "?")
    max_height = surf.get("max", "?")
    human_relation = surf.get("humanRelation", "Unknown")
    
    swells = wave_data.get("swells", [])
    swell_info = ""
    if swells:
        primary_swell = swells[0]
        height = primary_swell.get("height", "?")
        period = primary_swell.get("period", "?")
        swell_info = f" (Swell: {height}ft @ {period}s)"
    
    return f"{min_height}-{max_height}ft {human_relation}{swell_info}"


def print_forecast_summary(forecast: dict[str, Any], spot_name: str) -> None:
    """Print a formatted summary of the surf forecast."""
    print(f"\n{'='*70}")
    print(f"🏄 SURF FORECAST FOR: {spot_name}")
    print(f"{'='*70}")
    
    # Wave forecast
    if forecast.get("wave"):
        print("\n📊 WAVE FORECAST (Next 24-48 hours):")
        for i, wave_data in enumerate(forecast["wave"][:6], 1):
            ts = wave_data.get("timestamp")
            conditions = print_wave_conditions(wave_data)
            probability = wave_data.get("probability", 100)
            print(f"  [{i}] {format_timestamp(ts)} | {conditions} ({probability}% probability)")
    
    # Wind data
    if forecast.get("wind"):
        print("\n💨 WIND CONDITIONS:")
        for i, wind_data in enumerate(forecast["wind"][:4], 1):
            ts = wind_data.get("timestamp")
            speed = wind_data.get("speed", "?")
            direction = wind_data.get("direction", "?")
            direction_type = wind_data.get("directionType", "")
            gust = wind_data.get("gust", speed)
            print(f"  [{i}] {format_timestamp(ts)} | {speed:.1f} mph @ {direction:.0f}° {direction_type} (Gust: {gust:.1f})")
    
    # Weather
    if forecast.get("weather"):
        print("\n🌤️ WEATHER CONDITIONS:")
        for i, weather_data in enumerate(forecast["weather"][:4], 1):
            ts = weather_data.get("timestamp")
            temp = weather_data.get("temperature", "?")
            condition = weather_data.get("condition", "Unknown")
            pressure = weather_data.get("pressure", "?")
            condition_display = condition.replace("_", " ").title()
            print(f"  [{i}] {format_timestamp(ts)} | {temp:.0f}°F, {condition_display} ({pressure}mb)")
    
    # Tide information
    if forecast.get("tides"):
        print("\n🌊 TIDE INFORMATION:")
        for i, tide_data in enumerate(forecast["tides"][:4], 1):
            ts = tide_data.get("timestamp")
            height = tide_data.get("height", "?")
            tide_type = tide_data.get("type", "NORMAL")
            print(f"  [{i}] {format_timestamp(ts)} | {height:.2f}ft ({tide_type})")


def main():
    """Main execution: comprehensive workflow combining multiple API calls."""
    # Initialize client
    try:
        client = ParseClient()
    except ValueError as e:
        print(f"Error: {e}")
        return
    
    print("\n🏄 SURFLINE FORECAST ANALYZER")
    print("=" * 70)
    print("Searching for popular surf spots and analyzing conditions...")
    
    # Step 1: Get popular spots overview
    print("\n\n📍 DISCOVERING POPULAR SURF SPOTS")
    print("-" * 70)
    
    popular_spots_data = None
    try:
        popular_response = client.get_popular_spots()
        popular_spots_data = popular_response.get("data", {}).get("spots", [])
        
        if popular_spots_data:
            print(f"\n✅ Found {len(popular_spots_data)} popular spots")
            print("\nTop 5 Popular Spots:")
            for i, spot in enumerate(popular_spots_data[:5], 1):
                spot_name = spot.get("name", "Unknown")
                conditions = spot.get("conditions", {}).get("value", "N/A")
                surf_min = spot.get("surf", {}).get("min", "?")
                surf_max = spot.get("surf", {}).get("max", "?")
                wind_speed = spot.get("wind", {}).get("speed", "?")
                print(f"  {i}. {spot_name:25} | Condition: {conditions:8} | Surf: {surf_min:.1f}-{surf_max:.1f}ft | Wind: {wind_speed:.1f}mph")
        else:
            print("⚠️ No popular spots data returned")
    except Exception as e:
        print(f"⚠️ Error fetching popular spots: {e}")
    
    # Step 2: Search for specific destinations and get detailed forecasts
    print("\n\n🔍 DETAILED FORECAST ANALYSIS")
    print("-" * 70)
    
    destinations = ["Malibu", "Pipeline", "Rincon"]
    forecasts_retrieved = 0
    
    for destination in destinations:
        try:
            print(f"\n\n📡 Searching for: {destination}")
            search_result = client.search_spots(destination)
            
            spots = search_result.get("spots", [])
            if not spots:
                print(f"   ❌ No spots found for '{destination}'")
                continue
            
            # Get the first matching spot
            spot = spots[0]
            spot_id = spot.get("id")
            spot_name = spot.get("name")
            location = spot.get("location", {})
            breadcrumbs = spot.get("breadCrumbs", [])
            spot_type = spot.get("type", "spot")
            
            print(f"   ✅ Found: {spot_name} (Type: {spot_type})")
            if breadcrumbs:
                location_str = " > ".join(breadcrumbs)
                print(f"   📍 Location: {location_str}")
            if location:
                lat = location.get("lat", 0)
                lon = location.get("lon", 0)
                print(f"   🧭 Coordinates: {lat:.4f}, {lon:.4f}")
            
            # Get detailed forecast
            print(f"   ⏳ Fetching 3-day forecast...")
            forecast = client.get_spot_forecast(spot_id, days=3)
            
            # Display formatted forecast
            print_forecast_summary(forecast, spot_name)
            forecasts_retrieved += 1
            
        except requests.exceptions.RequestException as e:
            print(f"   ❌ Network error for {destination}: {e}")
        except (KeyError, ValueError, TypeError) as e:
            print(f"   ❌ Data processing error for {destination}: {e}")
        except Exception as e:
            print(f"   ❌ Unexpected error for {destination}: {e}")
    
    # Summary
    print(f"\n\n{'='*70}")
    print(f"✨ ANALYSIS COMPLETE")
    print(f"Successfully retrieved {forecasts_retrieved} detailed forecasts")
    print(f"{'='*70}\n")


if __name__ == "__main__":
    main()