WS-Dottie 🚢

Say hello to Dottie, your friendly TypeScript companion for Washington State transportation APIs

Meet Dottie - she's not just another API wrapper, she's your cheerful guide through Washington State's transportation data jungle. Whether you're tracking ferries across Puget Sound or monitoring traffic on I-5, Dottie makes it feel like you're chatting with a knowledgeable friend who happens to have real-time access to every traffic camera, weather station, and ferry terminal in the state.

WS-Dottie is a delightful TypeScript client library that wraps the Washington State Department of Transportation (WSDOT) and Washington State Ferries (WSF) APIs with smart caching, strict typing, automatic use of JSONP data fetching in browser environments to avoid CORS concerns, and seamless React Query integration. This little library allows you to fetch free, real-time commuter data with ease!

✨ Features

• 🚗 WSDOT APIs: Highway alerts, traffic flow, travel times, toll rates, weather, cameras, and more
• 🚢 WSF APIs: Vessel locations, terminal wait times, schedules, fares, and real-time data
• 🔄 Smart Caching: Built-in TanStack Query integration with optimized caching strategies
• 🌐 Cross-Platform: Automatic JSONP for web browsers, native fetch for Node.js
• 📱 React Ready: Hooks for all APIs with automatic cache management
• 🎯 TypeScript: Full type safety with comprehensive type definitions
• 🚀 Tree-Shaking: Only import what you need to keep bundles small

📦 Installation

npm install ws-dottie

🔑 API Key Setup

Get your free API key from WSDOT Developer Portal:

# For Node.js applications
export WSDOT_ACCESS_TOKEN=your_api_key_here

# For React/Expo applications
export EXPO_PUBLIC_WSDOT_ACCESS_TOKEN=your_api_key_here

🚀 Quick Start

Node.js Application

import { WsfVessels, WsdotHighwayAlerts, WsdotApiError } from 'ws-dottie';

// Get vessel locations
const vessels = await WsfVessels.getVesselLocations();

// Get highway alerts
const alerts = await WsdotHighwayAlerts.getHighwayAlerts();

// Handle errors gracefully
try {
  const data = await WsfVessels.getVesselLocations();
} catch (error) {
  if (error instanceof WsdotApiError) {
    console.log('API Error:', error.message);
  }
}

React Application

import { 
  useVesselLocations, 
  useHighwayAlerts, 
  WsdotApiError,
  tanstackQueryOptions 
} from 'ws-dottie';

function FerryApp() {
  const { data: vessels, isLoading, error } = useVesselLocations();
  const { data: alerts } = useHighwayAlerts();

  if (error instanceof WsdotApiError) {
    return <div>API Error: {error.message}</div>;
  }

  return (
    <div>
      {isLoading ? 'Loading...' : `Found ${vessels?.length} vessels`}
    </div>
  );
}

📚 Documentation

• Getting Started - Installation, setup, and basic usage
• API Reference - Complete API documentation
• Examples - Common use cases and patterns

🎯 Available APIs

WSDOT APIs

• Highway Alerts - Real-time traffic alerts and incidents
• Traffic Flow - Current traffic conditions and speeds
• Travel Times - Estimated travel times between locations
• Toll Rates - Current toll pricing information
• Weather Information - Road weather conditions and forecasts
• Highway Cameras - Live traffic camera feeds
• Bridge Clearances - Bridge height restrictions
• Mountain Pass Conditions - Pass status and restrictions
• Commercial Vehicle Restrictions - Truck and commercial vehicle limits
• Border Crossings - Border wait times and conditions
• Weather Stations - Weather station data and readings

WSF APIs

• Vessels - Real-time vessel locations and status
• Terminals - Terminal wait times and conditions
• Schedules - Ferry schedules and sailing times
• Fares - Fare information and pricing

🔧 Caching Configuration

WS-Dottie includes optimized caching strategies for different data types:

import { tanstackQueryOptions } from 'ws-dottie';

// Real-time data (5-second updates)
const realtimeConfig = tanstackQueryOptions.REALTIME_UPDATES;

// Minute updates (1-minute intervals)
const minuteConfig = tanstackQueryOptions.MINUTE_UPDATES;

// Hourly updates (1-hour intervals)
const hourlyConfig = tanstackQueryOptions.HOURLY_UPDATES;

// Daily updates (24-hour intervals)
const dailyConfig = tanstackQueryOptions.DAILY_UPDATES;

// Weekly updates (manual refresh only)
const weeklyConfig = tanstackQueryOptions.WEEKLY_UPDATES;

🤝 Contributing

We welcome contributions! Please see our development guide for setup instructions.

📄 License

MIT License - see LICENSE for details.

Made with ❤️ for Washington State travelers