Tides App

A web-based tide prediction application built with Streamlit that allows users to search for locations and view tide predictions from NOAA data.

Features

• Smart Location Search: Search for NOAA tide stations using geocoding and proximity matching
• Proximity-Based Results: Find the closest tide stations to any location worldwide
• Distance Information: See how far each station is from your search location
• Tide Predictions: View tide height predictions with interactive charts
• Arbitrary Date Ranges: Select any start date and duration (1-30 days)
• Multiple Time Ranges: Quick buttons for 1 day, 2 days, or 7 days of predictions
• Interactive Charts: Visualize tide data with Plotly charts
• Threshold Coloring: Areas below 2 feet are highlighted in red for safety awareness
• Threshold Crossing Labels: Automatic labels show when tide crosses the 2-foot level
• Data Tables: View detailed tide data in tabular format with crossing information
• Station Persistence: Automatic saving of selected stations to localStorage
• Direct Access: Access stations directly via URL with query parameters (e.g., ?station_id=8516945)
• Auto-Load: Saved stations automatically load when returning to the app
• Station Management: Search new stations or clear saved preferences

Installation

1. Install Poetry (if not already installed):

   curl -sSL https://install.python-poetry.org | python3 -

2. Install dependencies:

   poetry install
   poetry run pip install requests plotly pandas streamlit

Usage

1. Run the application:

   poetry run streamlit run tides_app.py

2. Open your browser and navigate to the URL shown in the terminal (typically http://localhost:8501)

3. Search for a location:

   • Enter a location name (e.g., "New York, NY", "San Francisco, CA", "Seattle, WA")
   • The app will geocode your location and find nearby tide stations
   • Results are sorted by distance, with the closest stations first

4. Select a station:

   • Choose from the list of available stations
   • Each station shows its distance from your search location
   • The app will automatically fetch today's tide data

5. View tide predictions:

   • Use the date picker to select any start date (up to 1 year in past/future)
   • Choose duration from 1 to 30 days
   • Use quick action buttons for common time periods
   • View the interactive chart showing tide heights over time
   • Areas below 2 feet are highlighted in red for safety awareness
   • Threshold crossing labels show when tide crosses the 2-foot level
   • Check the data table for specific values and crossing information

6. Manage stations:

   • Your selected station is automatically saved for next time
   • Use "🔍 Search New Station" to find a different location
   • Use "🗑️ Clear Saved Station" to remove your saved preference
   • Access stations directly via URL: http://localhost:8501/?station_id=8516945

Data Source

This application uses the NOAA Tides & Currents API to fetch tide prediction data. The data includes:

• Tide height predictions in feet
• Time intervals (typically 6-minute intervals)
• Station information (name, location, coordinates)

API Endpoints

The app uses the following NOAA API endpoint format:

https://api.tidesandcurrents.noaa.gov/api/prod/datagetter?product=predictions&application=NOS.COOPS.TAC.WL&begin_date=YYYYMMDD&end_date=YYYYMMDD&datum=MLLW&station=STATION_ID&time_zone=GMT&units=english&interval=&format=json

Development

Project Structure

• tides_app.py - Main Streamlit application
• noaa_client.py - Custom NOAA API client with geocoding and proximity search
• test_noaa_api.py - API integration test script
• test_proximity_search.py - Proximity search functionality test script
• test_chart_coloring.py - Chart coloring functionality test script
• test_date_range.py - Arbitrary date range functionality test script
• test_threshold_crossings.py - Threshold crossing detection test script
• test_localstorage_features.py - localStorage and query parameter functionality test script
• pyproject.toml - Poetry configuration and dependencies
• ARCHITECTURE.md - Detailed application specification

Dependencies

• streamlit - Web framework for building the UI
• requests - HTTP client for API calls
• plotly - Interactive charts and visualizations
• pandas - Data manipulation and analysis
• noaa - NOAA API client (for reference, but using custom implementation)

Note on Rio Framework

The original specification called for using Rio as the web framework. However, Rio is currently in development and not available as a standard Python package. This implementation uses Streamlit as an alternative, but the code structure and functionality are designed to be easily convertible to Rio when it becomes available.

To convert to Rio when available:

1. Replace Streamlit imports with Rio imports
2. Convert Streamlit components to Rio components
3. Update the session state management to Rio's state system
4. Replace Streamlit's plotting with Rio's HTML component for Plotly

Adding New Features

1. Smart Station Search: ✅ COMPLETED - Now uses geocoding and proximity matching

   • Custom NOAA client (noaa_client.py) with geocoding capabilities
   • Proximity-based station search using Haversine distance calculation
   • Real-time station data from NOAA's official API
   • Fallback to text-based search if geocoding fails
   • Distance information displayed for each station

2. High/Low Tide Detection: The current implementation uses a simplified approach. For more accurate detection:

   • Implement peak detection algorithms
   • Use tide prediction algorithms
   • Consider astronomical factors

3. Additional Features:

   • Save favorite locations
   • Tide alerts and notifications
   • Historical tide data
   • Multiple station comparison

Troubleshooting

Common Issues

1. No stations found: Try different search terms or check your internet connection
2. No tide data: Some stations may not have prediction data available
3. Chart not loading: Ensure Plotly is properly installed and check browser console for errors

Error Messages

• "Failed to fetch tide data": Check your internet connection and try again
• "No tide data available": The selected station may not have prediction data for the requested time period

License

This project is open source and available under the MIT License.