SkyBrief Weather API Stack - Implementation Guide

Date: 2024
Purpose: Development and Production Weather Data Stack
Status: Two Paths Available - Tomorrow.io Stack OR Meteoblue Path

Path A: Tomorrow.io Stack (Current)

1. Tomorrow.io (Free Tier)

URL: https://app.tomorrow.io/signin?return_to=%2Fdevelopment%2Fkeys
What you get: 500 calls/day, 5-day forecast
Upgrade cost: ~$500-1,000/month (Enterprise)
Time to get key: ~5 minutes
Cost: FREE (for testing)

Steps: 1. Sign up with email 2. Navigate to "Development Keys" 3. Generate API key 4. Copy key for use in SkyBrief

2. Windy.com (Testing Tier) - Map Forecast API

URL: https://api.windy.com/keys
What you get: 500 sessions/day, map tiles for visualization
Time to get key: ~5 minutes
Cost: FREE (development only)

Steps: 1. Create account at windy.com 2. Go to API keys section 3. Select "Map Forecast API" (NOT Point Forecast) 4. Generate testing key

Why Map Forecast? - You need weather overlay tiles for Mapbox - Tomorrow.io already provides forecast data - Point Forecast would be redundant (and shuffled in testing tier anyway)

Path B: Meteoblue from Day 1 (Alternative)

Choose this if: OK with €1,200/year after month 12, want EU data from start

1. Meteoblue (Free Tier - 1 Year)

URL: https://www.meteoblue.com/en/weather-api/
What you get: Unlimited calls, 1-year limit, non-commercial
Upgrade cost: €1,200/year (Bronze) after year 1
Time to get key: ~10 minutes
Cost: FREE (first 12 months only)

Advantages over Tomorrow.io: - Unlimited API calls (no 500/day limit) - EU data residency (GDPR compliant) - Better European models (NEMS4 at 4km) - No API migration needed when upgrading - Ground radar updates (5-15 min vs 60 min)

Steps: 1. Create account at meteoblue.com 2. Request free API access (1 year) 3. Confirm non-commercial use 4. Generate API key

2. AviationWeather.gov (Required for Both Paths)

URL: https://aviationweather.gov/api/data/metar
What you get: Official METAR/TAF/SIGMET data, unlimited calls
Signup required: NO - direct API access
Cost: FREE (NOAA/US Government)

Research Findings - Will This Stack Work?

Tomorrow.io Deep Dive

API Structure: 

Base URL: https://api.tomorrow.io/v4/
Endpoints:
- /weather/realtime - Current conditions
- /weather/forecast - Forecast data
- /timelines - Multiple variables, multiple time steps (EFFICIENT)
- /route - Weather along flight paths
- /map/tile/{z}/{x}/{y} - Map tiles

Rate Limits (Free Tier): - 500 requests/day - 25 requests/hour - 3 requests/second

Your Usage Calculation: - 40 flights/day - 3 calls per flight (origin, destination, route) - = 120 calls/day - Headroom: 380 calls/day remaining (3.8x safety margin)

✅ VERDICT: Sufficient for testing, tight for production

Data Available: - Temperature, humidity, dew point - Wind speed, direction, gusts - Precipitation (rain, snow, type) - Cloud cover (low, mid, high) - Visibility - Pressure - CAPE index (convective potential) - NO: METAR, TAF, SIGMET, official aviation data

Update Frequency: - Real-time: ~10-15 minutes - Forecasts: Updated hourly - Map tiles: Available but count toward limit

EU Data Residency: - ❌ US-based servers - ⚠️ May have GDPR implications for EU customers

Pricing: - Free Tier: 500 calls/day, 25/hour, 3/sec - €0 - Enterprise: Contact sales for pricing - ~$500-1,000/month estimated - 14-day forecasts - Minutely resolution - Unlimited calls - Premium features (lightning, air quality)

⚠️ Important: Free tier is permanent but limited. Enterprise requires contacting sales (no self-service upgrade).

Windy.com Map Forecast API Deep Dive

What You Get: - Weather map tiles for Mapbox integration - Visual layers: wind, temperature, pressure, clouds, precipitation - 500 sessions/day (each tile load = 1 session) - Testing tier uses shuffled/modified data

API Structure: 

Base URL: Uses Windy's map tile server
Integration: Add as tile layer in Mapbox
Example layers: wind, temp, pressure, clouds

What "Shuffled Data" Means: - Map tiles show real weather patterns - Values are modified by ±10-20% for testing - Visual appearance is correct (good for UI testing) - NOT suitable for operational flight decisions - ✅ Perfect for UI development and testing

Why Map Forecast (not Point Forecast): - Tomorrow.io already provides forecast data (JSON) - Windy Point Forecast would be redundant - Map tiles are what you need for visualization - Both APIs cost the same (€990/year Professional)

API Structure: 

Base URL: https://api.windy.com/api/point-forecast/v2
Method: POST
Body: {
    "lat": 49.809,
    "lon": 16.787,
    "model": "gfs",
    "parameters": ["wind", "temp", "pressure"],
    "key": "your_api_key"
}

Available Models (Testing): - GFS (Global) only - IconEU, AROME, etc. require Professional tier

Available Parameters (Testing): - Wind, temperature, pressure - Limited to: wind, temp, pressure only

Rate Limits: - 500 sessions/day - Each API call = 1 session

✅ VERDICT: Good for UI testing, not for operational data

AviationWeather.gov Deep Dive

Why This is Critical: This is your only source for official aviation weather. Tomorrow.io and Windy provide forecast models, but NOT certified aviation reports.

API Endpoints: 

METAR: https://aviationweather.gov/api/data/metar?ids=LEMD
TAF: https://aviationweather.gov/api/data/taf?ids=LEMD
Station Info: https://aviationweather.gov/api/data/station?ids=LEMD

Rate Limits: - No documented limits - NOAA encourages reasonable use - Estimated: thousands of calls/day acceptable

Data Format: - Returns raw METAR/TAF strings - Example: LEMD 051200Z 32008KT 9999 FEW040 15/08 Q1020 NOSIG - You'll need to parse this yourself

Coverage: - Global ICAO airports - Updated every 20-60 minutes - Real observations (not forecasts)

✅ VERDICT: Essential for EASA compliance, completely free

Integration Architecture

┌─────────────────────────────────────────────────────────────┐
│                    SkyBrief Backend                        │
│                      (Go/Echo)                             │
└────────────┬────────────┬────────────┬──────────────────────┘
             │            │            │
    ┌────────▼────────┐   │   ┌────────▼────────┐
    │  Tomorrow.io    │   │   │  AviationWeather │
    │   (Forecasts)   │   │   │   (METAR/TAF)   │
    │  120 calls/day  │   │   │   Unlimited     │
    └────────┬────────┘   │   └────────┬────────┘
             │            │            │
             │    ┌───────▼────────┐   │
             │    │  Windy.com     │   │
             │    │  (Maps/Tiles)  │   │
             │    │  500 sessions  │   │
             │    └───────┬────────┘   │
             │            │            │
             └────────────┴────────────┘
                          │
             ┌────────────▼────────────┐
             │    React Frontend       │
             │    (Mapbox + Charts)    │
             └─────────────────────────┘

Adapter Pattern Implementation

// internal/adapters/weather/ports.go

type WeatherProvider interface {
    GetForecast(ctx context.Context, lat, lon float64) (*Forecast, error)
    GetCurrent(ctx context.Context, lat, lon float64) (*CurrentWeather, error)
}

type AviationProvider interface {
    GetMETAR(ctx context.Context, icao string) (*METAR, error)
    GetTAF(ctx context.Context, icao string) (*TAF, error)
    GetSIGMETs(ctx context.Context, icao string) ([]SIGMET, error)
}

type MapProvider interface {
    GetTileURL(layer string, z, x, y int) string
}

Rate Limiting Strategy

Tomorrow.io (Critical): 

// Implement rate limiter: 25/hour, 500/day
limiter := rate.NewLimiter(rate.Every(time.Hour/25), 1)

// Cache responses for 15 minutes to reduce calls
cache := redis.NewClient(...)

Windy.com: 

// 500 sessions/day - generous for UI testing
// No caching needed for shuffled data

AviationWeather.gov: 

// No rate limiting needed
// Cache METAR for 10 minutes (updates every 20-60 min)
// Cache TAF for 30 minutes (updates every 6 hours)

Data Flow Per Flight Briefing

Example: Flight from Madrid (LEMD) to Barcelona (LEBL)

  1. AviationWeather.gov (3 calls)
  2. METAR LEMD
  3. METAR LEBL
  4. TAF LEMD

  5. TAF LEBL

  6. Tomorrow.io (3 calls)

  7. Forecast for LEMD (route origin)
  8. Forecast for LEBL (route destination)

  9. Route forecast (waypoints in between)

  10. Windy.com (Tile requests)

  11. Map tiles for route visualization
  12. Each tile = 1 session
  13. ~10-20 tiles per map view

Total per briefing: ~6 API calls + tiles

Daily at 40 flights: ~240 calls + tiles

Tomorrow.io headroom: 500 - 240 = 260 calls remaining

Risk Analysis

⚠️ Tomorrow.io Free Tier Risks

Risk 1: Exceeding Daily Limit - Probability: Medium (if you add more features) - Impact: API blocked until next day - Mitigation: Implement aggressive caching

Risk 2: Hitting Hourly Limit (25/hour) - Probability: Low (240 calls/day ÷ 16 hours = 15/hour) - Impact: Temporary slowdown - Mitigation: Spread calls evenly, use queue

Risk 3: US Data Residency - Probability: Depends on customer requirements - Impact: GDPR compliance issues - Mitigation: Plan migration to Meteoblue for production

✅ Windy.com Testing Tier Risks

Risk: Shuffled Data Only - Probability: 100% (by design) - Impact: Cannot use for operational decisions - Mitigation: Only use for UI testing, switch to Professional for production

✅ AviationWeather.gov Risks

Risk: Service Outages - Probability: Low (government infrastructure) - Impact: No METAR/TAF data - Mitigation: Cache data, implement fallback

Migration Path to Production

Month 6-12: Scale Testing

If you exceed 500 calls/day:

Option 1: Meteoblue Bronze (€1,200/year) - Pro: EU-based, clear pricing - Con: No Maps API (radar tiles)

Option 2: Windy.com Professional (€990/year) - Pro: Affordable, EU-based - Con: Limited aviation features

Option 3: Hybrid (~€1,500/year) - Meteoblue: Forecast data - Windy: Map tiles - AviationWeather: METAR/TAF

Production Architecture

┌─────────────────────────────────────────────────────────────┐
│                    SkyBrief Production                      │
│                                                             │
│  ┌──────────────┐  ┌──────────────┐  ┌─────────────────┐   │
│  │  Meteoblue   │  │  Windy.com   │  │AviationWeather  │   │
│  │   (Data)     │  │  (Map Tiles) │  │   (METAR/TAF)   │   │
│  │  ~€200/mo    │  │   ~€83/mo    │  │     FREE        │   │
│  └──────────────┘  └──────────────┘  └─────────────────┘   │
│                                                             │
│  Total: ~€283/month (~€3,400/year)                         │
└─────────────────────────────────────────────────────────────┘

Implementation Checklist

Phase 1: Setup (Week 1)

  • [ ] Sign up for Tomorrow.io API key
  • [ ] Sign up for Windy.com Map Forecast testing key
  • [ ] Test AviationWeather.gov endpoints
  • [ ] Verify rate limits with simple scripts

Phase 2: Adapters (Week 2)

  • [ ] Implement Tomorrow.io adapter with rate limiting
  • [ ] Implement Windy.com adapter for maps
  • [ ] Implement AviationWeather.gov adapter (METAR/TAF/SIGMET parser)
  • [ ] Create caching layer (Redis)

Phase 3: Integration (Week 3)

  • [ ] Build flight briefing endpoint
  • [ ] Integrate Mapbox with Windy tiles
  • [ ] Display METAR/TAF/SIGMET text in briefing
  • [ ] Add error handling and fallbacks

Phase 4: Testing (Week 4)

  • [ ] Monitor API usage (stay under limits)
  • [ ] Test with real flight scenarios
  • [ ] Validate data accuracy
  • [ ] Document any limitations

Phase 5: SIGMET Map Plotting (Post-MVP)

  • [ ] Download OurAirports navaid database
  • [ ] Build VOR/NDB waypoint → lat/lng converter
  • [ ] Parse SIGMET waypoint polygons
  • [ ] Plot SIGMETs on Mapbox with color coding
  • [ ] Add SIGMET layer toggle in UI

Cost Projection

Development (Months 1-6)

Provider Cost Notes
Tomorrow.io Free €0 500 calls/day
Windy.com Testing €0 Shuffled data
AviationWeather €0 Unlimited
TOTAL €0

Alternative Path: Meteoblue from Day 1

If willing to pay €1,200/year after month 12:

Phase Provider Cost Notes
Year 1 Meteoblue Free €0 Unlimited calls, 1 year limit
Year 2+ Meteoblue Bronze ~€400/mo €1,200/year base + per-call fees
Always AviationWeather €0 METAR/TAF/SIGMET
TOTAL €0 → €400/mo Seamless upgrade, no API changes

Advantages of Meteoblue path: - No rate limiting in development (unlimited calls vs 500/day) - EU data residency from day 1 (GDPR compliant) - Better European weather models (NEMS4 at 4km) - No API migration needed when upgrading - Ground radar updates (5-15 min vs 60 min satellite)

Current Path: Tomorrow.io Stack

Provider Cost Notes
Tomorrow.io Free €0 500 calls/day limit
OR Tomorrow.io Enterprise ~$500-1,000/mo Contact sales, unlimited
OR Meteoblue Bronze €100/mo If upgrade needed
Windy.com Map Forecast €83/mo Real map tiles
AviationWeather €0 Unlimited
TOTAL €0-183/mo (or $500-1,000)

Production (Month 13+)

Provider Cost Notes
Meteoblue Silver €200/mo Includes Maps API
OR Windy.com Map Forecast €83/mo Budget tiles
AviationWeather €0 Unlimited
TOTAL €83-200/mo

SIGMET Data for Map Plotting

What is SIGMET?

SIGMETs (Significant Meteorological Information) are weather advisories for: - Convective: Thunderstorms, severe turbulence - Non-convective: Icing, turbulence, volcanic ash, dust storms - Valid for: Up to 4 hours (convective) or 6 hours (non-convective)

Data Source: AviationWeather.gov (FREE)

Endpoint: https://aviationweather.gov/api/data/sigmet

What you get: - Raw SIGMET text with waypoint polygons - Convective and non-convective advisories - Polygon coordinates for plotting (using VOR/NDB waypoints) - Updates in real-time as issued

Example response: 

Type: SIGMET Hazard: CONVECTIVE
WSUS32 KKCI 051655
SIGC 
CONVECTIVE SIGMET 52C
VALID UNTIL 1855Z
TN KY
FROM 10SSW IIU-30NNW BNA-60SSW PXV-30ESE PXV-10SSW IIU
AREA EMBD TS MOV FROM 24040KT. TOPS TO FL290.

Plotting on Mapbox: The "FROM" line contains waypoint identifiers that form a polygon: 1. Parse waypoints (e.g., "10SSW IIU", "30NNW BNA") 2. Convert VOR/NDB stations to lat/lng coordinates 3. Draw polygon on Mapbox

// Example Mapbox polygon layer
map.addLayer({
  id: 'sigmet-convective',
  type: 'fill',
  source: {
    type: 'geojson',
    data: {
      type: 'Feature',
      geometry: {
        type: 'Polygon',
        coordinates: [/* converted waypoints */](<../../../* converted waypoints */.md>)
      },
      properties: {
        hazard: 'CONVECTIVE',
        validUntil: '1855Z'
      }
    }
  },
  paint: {
    'fill-color': '#ff0000',
    'fill-opacity': 0.3
  }
});

Cost: FREE (NOAA/US Government)

The Challenge: Waypoint Conversion

SIGMETs use VOR/NDB navigation aids (e.g., "BNA", "PXV") not lat/lng coordinates.

Solution Options:

Option A: Free Database (RECOMMENDED) - Download OurAirports navaid database (FREE) - Contains VOR/DME/NDB coordinates globally - Build simple lookup table - Cost: €0 - Effort: Medium (one-time setup)

Option B: Skip SIGMETs Initially - Focus on METAR/TAF first - Add SIGMETs in Phase 2 - Cost: €0 - Effort: Low

Option C: Commercial Service - Jeppesen, DTN, ARINC provide pre-converted SIGMETs - Ready-to-use GeoJSON polygons - Cost: $500-2,000/month - Effort: Low

Implementation Plan

Phase 1 (MVP): - Use AviationWeather.gov for SIGMET text display - Show raw SIGMET text in briefing (no map plotting) - Add waypoint conversion in Phase 2

Phase 2 (Enhanced): - Download OurAirports navaid data - Build waypoint → lat/lng converter - Plot SIGMET polygons on Mapbox - Color-code by hazard type: - Red: Convective (thunderstorms) - Orange: Turbulence - Yellow: Icing - Purple: Volcanic ash

Updated Data Stack

┌─────────────────────────────────────────────────────────────┐
│                    SkyBrief Data Sources                    │
├─────────────────────────────────────────────────────────────┤
│ Tomorrow.io        → Forecast data (temp, wind, clouds)     │
│ Windy.com          → Map tiles for visualization            │
│ AviationWeather    → METAR, TAF, SIGMET (official)          │
│ OurAirports        → Navaid coordinates (for SIGMET plotting)│
└─────────────────────────────────────────────────────────────┘

All sources: €0 cost

API Usage Impact

SIGMET calls: 1-2 per flight briefing - Check origin airport region - Check destination airport region - Check route corridor

Daily at 40 flights: ~60-80 SIGMET calls AviationWeather limit: Unlimited (no impact)

Open Questions to Resolve

  1. Tomorrow.io Route API: Does the /route endpoint count as 1 call or multiple?
  2. Action: Test with API key

  3. Impact: If multiple, reduces effective headroom

  4. Windy.com Tile Counting: How many tiles load per map view?

  5. Action: Test with browser dev tools

  6. Impact: Affects daily session usage

  7. AviationWeather.gov Limits: What's the practical daily limit?

  8. Action: Monitor during testing

  9. Impact: Currently assumed unlimited

  10. EU Data Residency: Do your customers require EU-only data?

  11. Action: Consult with legal/compliance

  12. Impact: May force early migration to Meteoblue

  13. Caching Strategy: How long to cache Tomorrow.io responses?

  14. Action: Test with 15-minute cache

  15. Impact: Reduces API calls significantly

  16. SIGMET Waypoint Conversion: Can we get OurAirports navaid data for VOR conversion?

  17. Action: Download and test OurAirports navaid database
  18. Impact: Required for Phase 2 SIGMET map plotting

Summary

✅ This Stack Will Work For: - Development and testing (0-12 months) - Up to 40 flights/day on Tomorrow.io Free - UI development with Windy shuffled data - Official METAR/TAF/SIGMET from AviationWeather - SIGMET text display (Phase 1) and map plotting (Phase 2)

⚠️ Limitations: - 500 calls/day is tight (240 used, 260 remaining) - No radar tiles without Rain Viewer - US-based data (Tomorrow.io) - Shuffled Windy data (testing only) - SIGMET plotting requires waypoint conversion (VOR → lat/lng)

🎯 Two Implementation Paths:

Path A: Tomorrow.io Stack (Current Document) - Best if: Uncertain about timeline, want to test multiple providers - Year 1: €0 (Tomorrow.io Free + Windy Testing) - Year 2+: €0-183/month or migrate to Meteoblue

Path B: Meteoblue from Day 1 ✅ Recommended if okay with €1,200/year after month 12 - Best if: Want EU data from start, unlimited calls in development - Year 1: €0 (Meteoblue Free - unlimited calls) - Year 2+: ~€400/month (Meteoblue Bronze) - Advantages: No API migration, EU data residency, better European models

🔄 Migration Ready: - Adapter pattern allows easy swap between providers - Same API structure, different endpoints - Can migrate in 1-2 weeks when ready - Choose Path A or B based on your preference

Document Version: 1.0
Last Updated: 2024
Next Review: After API keys obtained

results matching ""

    No results matching ""