pywindsurf

Unofficial Python client library and CLI for the iWindsurf API.

Installation

pip install .

For development:

pip install -e ".[dev]"

Client Library

Sync client

from pywindsurf import WindsurfClient

with WindsurfClient(wf_token="your-token") as client:
    # Get current conditions for one or more spots
    spots = client.get_spot_details([163947])
    for spot in spots:
        obs = spot.get_latest_observation()
        print(f"{spot.name}: {obs['avg']} kts {obs['dir_text']}")

    # Get wind history (last 25 hours)
    graph = client.get_graph(163947, hours_back=25)
    print(f"Last ob: {graph.last_ob_avg} kts {graph.last_ob_dir_txt}")

    # Get forecast from a specific model
    forecast = client.get_model_data(163947, model_id=276)
    print(f"{forecast.model_short_name}: max {forecast.max_wind} kts")

    # List available forecast models
    models = client.get_available_models(163947)
    for m in models:
        print(f"{m.model_short_name} (id={m.model_id})")

    # Search for spots by location name
    spots = client.search_spots("miami")
    for spot in spots:
        obs = spot.get_latest_observation()
        print(f"{spot.name} ({spot.spot_id}): {obs['avg']} kts")

    # Get daily observation summary
    summary = client.get_observation_summary(
        163947,
        time_start_local="2026-03-03 00:00:00",
        time_end_local="2026-03-03 23:59:59",
    )
    print(f"Temp: {summary.air_temp_min}-{summary.air_temp_max}°F")

Async client

import asyncio
from pywindsurf import AsyncWindsurfClient

async def main():
    async with AsyncWindsurfClient(wf_token="your-token") as client:
        spots = await client.get_spot_details(163947)
        graph = await client.get_graph(163947)
        forecast = await client.get_model_data(163947, model_id=276)

asyncio.run(main())

Unit options

from pywindsurf import WindsurfClient, WindUnit, TempUnit

client = WindsurfClient(
    wf_token="your-token",
    units_wind=WindUnit.MPH,
    units_temp=TempUnit.CELSIUS,
)

CLI

The CLI requires a WF_TOKEN environment variable:

export WF_TOKEN=your-token

Commands

# Search for spots near a location
pywindsurf search miami

# Search with custom radius and limit
pywindsurf search "san francisco" --distance 100 --limit 10

# Current conditions + daily summary
pywindsurf spot 163947

# Multiple spots
pywindsurf spot 163947 163946

# Wind history chart (last 25 hours)
pywindsurf graph 163947

# Wind history as a table
pywindsurf graph 163947 --table

# Custom time range
pywindsurf graph 163947 --hours 12

# Forecast chart (prompts for model selection)
pywindsurf forecast 163947

# Forecast with a specific model
pywindsurf forecast 163947 --model-id 276

# Forecast as a table
pywindsurf forecast 163947 --model-id 276 --table

# List available forecast models
pywindsurf models 163947

# Sunrise/sunset times
pywindsurf sun 163947

# Everything at once (spot + graph + sun + forecast)
pywindsurf full 163947 --model-id 276

# Everything as tables
pywindsurf full 163947 --model-id 276 --table