SKILL.md

$27

Setup

Project Configuration

Enable the WeatherKit capability in Xcode (adds the entitlement)

Enable WeatherKit for your App ID in the Apple Developer portal

Add NSLocationWhenInUseUsageDescription to Info.plist if using device location

WeatherKit requires an active Apple Developer Program membership

Import

import WeatherKit

import CoreLocation

Creating the Service

Use the shared singleton or create an instance. The service is Sendable and

thread-safe.

let weatherService = WeatherService.shared

// or

let weatherService = WeatherService()

Fetching Current Weather

Fetch current conditions for a location. Returns a Weather object with all

available datasets.

func fetchCurrentWeather(for location: CLLocation) async throws -> CurrentWeather {

    let weather = try await weatherService.weather(for: location)

    return weather.currentWeather

}

// Using the result

func displayCurrent(_ current: CurrentWeather) {

    let temp = current.temperature  // Measurement<UnitTemperature>

    let condition = current.condition  // WeatherCondition enum

    let symbol = current.symbolName  // SF Symbol name

    let humidity = current.humidity  // Double (0-1)

    let wind = current.wind  // Wind (speed, direction, gust)

    let uvIndex = current.uvIndex  // UVIndex

    print("\(condition): \(temp.formatted())")

}

Forecasts

Hourly Forecast

Returns 25 contiguous hours starting from the current hour by default.

func fetchHourlyForecast(for location: CLLocation) async throws -> Forecast<HourWeather> {

    let weather = try await weatherService.weather(for: location)

    return weather.hourlyForecast

}

// Iterate hours

for hour in hourlyForecast {

    print("\(hour.date): \(hour.temperature.formatted()), \(hour.condition)")

}

Daily Forecast

Returns 10 contiguous days starting from the current day by default.

func fetchDailyForecast(for location: CLLocation) async throws -> Forecast<DayWeather> {

    let weather = try await weatherService.weather(for: location)

    return weather.dailyForecast

}

// Iterate days

for day in dailyForecast {

    print("\(day.date): \(day.lowTemperature.formatted()) - \(day.highTemperature.formatted())")

    print("  Condition: \(day.condition), Precipitation: \(day.precipitationChance)")

}

Custom Date Range

Request forecasts for specific date ranges using WeatherQuery.

func fetchExtendedForecast(for location: CLLocation) async throws -> Forecast<DayWeather> {

    let startDate = Date.now

    let endDate = Calendar.current.date(byAdding: .day, value: 10, to: startDate)!

    let forecast = try await weatherService.weather(

        for: location,

        including: .daily(startDate: startDate, endDate: endDate)

    )

    return forecast

}

Weather Alerts

Fetch active weather alerts for a location. Alerts include severity, summary,

and affected regions.

func fetchAlerts(for location: CLLocation) async throws -> [WeatherAlert]? {

    let weather = try await weatherService.weather(for: location)

    return weather.weatherAlerts

}

// Process alerts

if let alerts = weatherAlerts {

    for alert in alerts {

        print("Alert: \(alert.summary)")

        print("Severity: \(alert.severity)")

        print("Region: \(alert.region)")

        if let detailsURL = alert.detailsURL {

            // Link to full alert details

        }

    }

}

Selective Queries

Fetch only the datasets you need to minimize API usage and response size. Each

WeatherQuery type maps to one dataset.

Single Dataset

let current = try await weatherService.weather(

    for: location,

    including: .current

)

// current is CurrentWeather

Multiple Datasets

let (current, hourly, daily) = try await weatherService.weather(

    for: location,

    including: .current, .hourly, .daily

)

// current: CurrentWeather, hourly: Forecast<HourWeather>, daily: Forecast<DayWeather>

Minute Forecast

Available in limited regions. Returns precipitation forecasts at minute

granularity for the next hour.

let minuteForecast = try await weatherService.weather(

    for: location,

    including: .minute

)

// minuteForecast: Forecast<MinuteWeather>?  (nil if unavailable)

Available Query Types

Query

Return Type

Description

.current

CurrentWeather

Current observed conditions

.hourly

Forecast<HourWeather>

25 hours from current hour

.daily

Forecast<DayWeather>

10 days from today

.minute

Forecast<MinuteWeather>?

Next-hour precipitation (limited regions)

.alerts

[WeatherAlert]?

Active weather alerts

.availability

WeatherAvailability

Dataset availability for location

Attribution

Apple requires apps using WeatherKit to display attribution. This is a

legal requirement.

Fetching Attribution

func fetchAttribution() async throws -> WeatherAttribution {

    return try await weatherService.attribution

}

Displaying Attribution in SwiftUI

import SwiftUI

import WeatherKit

struct WeatherAttributionView: View {

    let attribution: WeatherAttribution

    @Environment(\.colorScheme) private var colorScheme

    var body: some View {

        VStack {

            // Display the Apple Weather mark

            AsyncImage(url: markURL) { image in

                image

                    .resizable()

                    .scaledToFit()

                    .frame(height: 20)

            } placeholder: {

                EmptyView()

            }

            // Link to the legal attribution page

            Link("Weather data sources", destination: attribution.legalPageURL)

                .font(.caption2)

                .foregroundStyle(.secondary)

        }

    }

    private var markURL: URL {

        colorScheme == .dark

            ? attribution.combinedMarkDarkURL

            : attribution.combinedMarkLightURL

    }

}

Attribution Properties

Property

Use

combinedMarkLightURL

Apple Weather mark for light backgrounds

combinedMarkDarkURL

Apple Weather mark for dark backgrounds

squareMarkURL

Square Apple Weather logo

legalPageURL

URL to the legal attribution web page

legalAttributionText

Text alternative when a web view is not feasible

serviceName

Weather data provider name

Availability

Check which weather datasets are available for a given location. Not all datasets

are available in all countries.

func checkAvailability(for location: CLLocation) async throws {

    let availability = try await weatherService.weather(

        for: location,

        including: .availability

    )

    // Check specific dataset availability

    if availability.alertAvailability == .available {

        // Safe to fetch alerts

    }

    if availability.minuteAvailability == .available {

        // Minute forecast available for this region

    }

}

Common Mistakes

DON'T: Ship without Apple Weather attribution

Omitting attribution violates the WeatherKit terms of service and risks App Review

rejection.

// WRONG: Show weather data without attribution

VStack {

    Text("72F, Sunny")

}

// CORRECT: Always include attribution

VStack {

    Text("72F, Sunny")

    WeatherAttributionView(attribution: attribution)

}

DON'T: Fetch all datasets when you only need current conditions

Each dataset query counts against your API quota. Fetch only what you display.

// WRONG: Fetches everything

let weather = try await weatherService.weather(for: location)

let temp = weather.currentWeather.temperature

// CORRECT: Fetch only current conditions

let current = try await weatherService.weather(

    for: location,

    including: .current

)

let temp = current.temperature

DON'T: Ignore minute forecast unavailability

Minute forecasts return nil in unsupported regions. Force-unwrapping crashes.

// WRONG: Force-unwrap minute forecast

let minutes = try await weatherService.weather(for: location, including: .minute)

for m in minutes! { ... } // Crash in unsupported regions

// CORRECT: Handle nil

if let minutes = try await weatherService.weather(for: location, including: .minute) {

    for m in minutes { ... }

} else {

    // Minute forecast not available for this region

}

DON'T: Forget the WeatherKit entitlement

Without the capability enabled, WeatherService calls throw at runtime.

// WRONG: No WeatherKit capability configured

let weather = try await weatherService.weather(for: location) // Throws

// CORRECT: Enable WeatherKit in Xcode Signing &#x26; Capabilities

// and in the Apple Developer portal for your App ID

DON'T: Make repeated requests without caching

Weather data updates every few minutes, not every second. Cache responses

to stay within API quotas and improve performance.

// WRONG: Fetch on every view appearance

.task {

    let weather = try? await fetchWeather()

}

// CORRECT: Cache with a staleness interval

actor WeatherCache {

    private var cached: CurrentWeather?

    private var lastFetch: Date?

    func current(for location: CLLocation) async throws -> CurrentWeather {

        if let cached, let lastFetch,

           Date.now.timeIntervalSince(lastFetch) < 600 {

            return cached

        }

        let fresh = try await WeatherService.shared.weather(

            for: location, including: .current

        )

        cached = fresh

        lastFetch = .now

        return fresh

    }

}