Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/OdintheDoggo/GodotNWS/llms.txt

Use this file to discover all available pages before exploring further.

GodotNWS exposes two forecast feeds from the NWS API: a daily forecast that covers the next several days in named periods (e.g. “This Afternoon”, “Tonight”, “Tuesday”), and an hourly forecast that provides conditions for every hour over the next several days. Both feeds return typed resource objects and emit a signal when data is ready.
Location setup must complete before calling any fetch method. See the Location Setup guide and wait for location_setup_complete before proceeding.

​
Daily Forecast

​
Fetching

Call Nws.fetch_forecast(fetch_images) to request the multi-day forecast. When the data is ready, the forecast_fetched signal fires with an array of ForecastPeriod resources. 
func _ready() -> void:
    Nws.location_setup_complete.connect(_on_location_ready)
    Nws.setup(39.9526, -75.1652)  # Philadelphia, PA

func _on_location_ready() -> void:
    Nws.forecast_fetched.connect(_on_forecast)
    Nws.fetch_forecast(true)  # true = also download icon images

func _on_forecast(periods: Array[ForecastPeriod]) -> void:
    # Sort by period number so day/night ordering is correct
    periods.sort_custom(func(a, b): return a.number < b.number)

    for period in periods:
        var label = "Day" if period.isDay else "Night"
        print("[%s] %s (%s)" % [label, period.name, period.temperatureUnit])
        print("  Temp:   %s°%s" % [period.temperature, period.temperatureUnit])
        print("  Precip: %s%%" % period.precipitationChance)
        print("  Wind:   %s from %s°" % [period.windSpeed, period.windDirection])
        print("  Short:  %s" % period.shortForecast)
        print("  Detail: %s" % period.detailedForecast)
        if period.icon:
            $ForecastIcon.texture = period.icon

​
The fetch_images Parameter

ValueBehaviour
trueDownloads the NWS icon PNG for each period. period.icon will be an ImageTexture. Each icon is fetched asynchronously.
falseSkips image downloads. period.icon will be null, but period.iconUrl is always populated with the URL string. Faster and bandwidth-friendly.
When fetch_images is true, image downloads happen concurrently. The forecast_fetched signal fires only after all icons have arrived, but the periods inside the array may not be in chronological order. Always sort by period.number before displaying.

​
ForecastPeriod Fields

FieldTypeDescription
rawDictionaryThe full raw JSON properties for this period from the NWS API.
numberintPeriod index starting at 1. Odd = daytime, even = night (generally).
nameStringHuman-readable period name, e.g. "Tonight", "Wednesday".
startTimeDictionaryPeriod start as a Godot datetime dict (year, month, day, hour, minute, second, weekday, dst).
endTimeDictionaryPeriod end as a Godot datetime dict.
isDaybooltrue if this is a daytime period.
temperaturefloatForecast temperature.
temperatureUnitString"F" or "C" depending on the NWS grid.
precipitationChancefloatProbability of precipitation as a percentage (0–100).
windSpeedfloatWind speed value for the period.
windDirectionfloatWind direction in degrees.
iconImageTextureDownloaded icon image, or null if fetch_images was false.
iconUrlStringURL of the NWS condition icon, always populated.
shortForecastStringBrief condition summary, e.g. "Mostly Cloudy".
detailedForecastStringFull narrative forecast text for the period.
Use period.isDay to apply day/night visual styling — for example, switching between a sun icon and a moon icon, or adjusting your UI background colors.

​
Hourly Forecast

​
Fetching

Call Nws.fetch_hourly_forecast(fetch_images) for per-hour conditions. The signal hourly_forecast_fetched fires with an array of HourlyForecastPeriod resources. Hourly periods do not have a name field. 
func _on_location_ready() -> void:
    Nws.hourly_forecast_fetched.connect(_on_hourly)
    Nws.fetch_hourly_forecast(false)  # Skip icons for speed

func _on_hourly(periods: Array[HourlyForecastPeriod]) -> void:
    periods.sort_custom(func(a, b): return a.number < b.number)

    for period in periods:
        var hour = period.startTime["hour"]
        print("%02d:00 — %s°%s, humidity %s%%, dewpoint %s°" % [
            hour,
            period.temperature,
            period.temperatureUnit,
            period.relativeHumidity,
            period.dewpoint
        ])

​
HourlyForecastPeriod Fields

HourlyForecastPeriod has the same fields as ForecastPeriod except there is no name field. It adds two extra fields:
FieldTypeDescription
rawDictionaryFull raw JSON properties from the NWS API.
numberintHour index starting at 1. Use this to sort periods into chronological order.
startTimeDictionaryHour start as a Godot datetime dict.
endTimeDictionaryHour end as a Godot datetime dict.
isDaybooltrue if this hour falls during daytime.
temperaturefloatTemperature for this hour.
temperatureUnitString"F" or "C".
precipitationChancefloatProbability of precipitation (0–100).
dewpointfloatDewpoint temperature in the same unit as temperature.
relativeHumidityfloatRelative humidity as a percentage (0–100).
windSpeedfloatWind speed for this hour.
windDirectionfloatWind direction in degrees.
iconImageTextureDownloaded icon, or null if icons were not fetched.
iconUrlStringURL of the NWS condition icon, always populated.
shortForecastStringBrief condition summary.
detailedForecastStringFull narrative text for this hour.
The same sort-by-number rule applies to hourly periods when fetch_images is true. Async image downloads complete in unpredictable order, so always sort before iterating for display.

Build docs developers (and LLMs) love

Get started for freeTalk to us