Weather Methods

Access weather data for any location worldwide.

Overview

The Weather Methods provide access to current weather conditions and forecast data through the TelemetryOS API. Applications can query weather by city name, postal code, or geographic coordinates, with support for imperial and metric units and localized responses.

Importing

import { weather } from '@telemetryos/sdk';

Methods

getConditions()

Retrieve current weather conditions for a specified location.

Signature:

async getConditions(params: WeatherRequestParams): Promise<WeatherConditions>

Parameters:

params - Weather request parameters

WeatherRequestParams:

type WeatherRequestParams = {
  city?: string;              // City name (e.g., "New York" or "London, UK")
  postalCode?: string;        // Postal/ZIP code (alternative to city)
  lat?: string;               // Latitude (if city not provided)
  lon?: string;               // Longitude (if city not provided)
  units?: 'imperial' | 'metric';  // Units system (default: imperial)
  language?: string;          // Language code for localized responses
}

Returns: Promise<WeatherConditions> - Current weather conditions

Example:

const conditions = await weather().getConditions({
  city: 'New York',
  units: 'imperial'
});

getDailyForecast()

Retrieve daily weather forecast for a specified location.

Signature:

async getDailyForecast(params: DailyForecastParams): Promise<WeatherForecast[]>

Parameters:

params - Forecast request parameters

DailyForecastParams:

type DailyForecastParams = WeatherRequestParams & {
  days?: number;  // Number of days to forecast (default: 5)
}

Returns: Promise<WeatherForecast[]> - Array of daily forecast data

Example:

const forecast = await weather().getDailyForecast({
  city: 'London',
  units: 'metric',
  days: 5
});

getHourlyForecast()

Retrieve hourly weather forecast for a specified location.

Signature:

async getHourlyForecast(params: HourlyForecastParams): Promise<WeatherForecast[]>

Parameters:

params - Forecast request parameters

HourlyForecastParams:

type HourlyForecastParams = WeatherRequestParams & {
  hours?: number;  // Number of hours to forecast (default: 24)
}

Returns: Promise<WeatherForecast[]> - Array of hourly forecast data

Example:

const forecast = await weather().getHourlyForecast({
  city: 'Tokyo',
  units: 'metric',
  hours: 24
});

Types

WeatherConditions

type WeatherConditions = {
  CityLocalized: string;         // City name (localized)
  CityEnglish: string;           // City name (English)
  WindAbbr: string;              // Wind abbreviation
  CountryCode: string;           // ISO country code
  Timezone: string;              // Timezone
  WeatherText: string;           // Weather description text
  State: string;                 // State/Province
  Pod: string;                   // Part of day (day/night indicator)
  WeatherCode: string;           // Weather code (internal mapping)
  WindDirectionDegrees: string;  // Wind direction in degrees
  WindDirectionEnglish: string;  // Wind direction (cardinal, English)
  WindDirectionLocalized: string; // Wind direction (localized)
  RelativeHumidity: number;      // Relative humidity percentage
  Timestamp: number;             // Unix timestamp
  Longitude: number;             // Longitude
  Latitude: number;              // Latitude
  Temp: number;                  // Current temperature
  Pressure: number;              // Atmospheric pressure
  WindSpeed: number;             // Wind speed
  Visibility: number;            // Visibility distance
  Precip: number;                // Precipitation amount
}

WeatherForecast

type WeatherForecast = {
  Datetime: string;     // ISO datetime string
  Pod: string;          // Part of day (day/night indicator)
  Label: string;        // Weather description label
  WeatherCode: string;  // Weather code
  Timestamp: number;    // Unix timestamp
  Temp: number;         // Temperature
  MinTemp: number;      // Minimum temperature
  MaxTemp: number;      // Maximum temperature
}

Next Steps

Storage Methods - Cache weather data for offline access
Media Methods - Display weather-appropriate content
Code Examples - Complete weather application example