Guides
Start typing to search…

Weather Methods

Access weather data including current conditions, daily forecasts, hourly forecasts, and severe weather alerts with dual-unit responses (metric and imperial).

Weather Methods

Access weather data for any location worldwide with dual-unit responses.

Overview

The Weather Methods provide access to current weather conditions, forecasts, and alerts through the TelemetryOS API. The API uses city IDs for location lookup and returns both metric and imperial units in every response, eliminating the need to specify a unit preference.

Key features:

  • City-based lookup: Use getCities() to search for locations and obtain a cityId
  • Dual-unit responses: Every response includes both metric (Celsius, km/h, mm) and imperial (Fahrenheit, mph, inches) values
  • Localization: Optional language parameter for localized weather descriptions

Importing

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

Methods

getCities()

Search for cities by name or country to obtain a cityId for use with other weather methods.

Signature:

async getCities(params: CitiesSearchParams): Promise<WeatherCity[]>

Parameters:

  • params - City search parameters

CitiesSearchParams:

type CitiesSearchParams = {
  countryCode?: string;  // ISO country code filter (e.g., "US", "CA")
  search?: string;       // City name search query (case-insensitive prefix match)
}

Returns: Promise<WeatherCity[]> - Array of matching cities

Example:

// Search for cities named "Vancouver"
const cities = await weather.getCities({ search: 'Vancouver' });

// Get the cityId for weather queries
const cityId = cities[0].cityId;

// Filter by country
const usCities = await weather.getCities({
  search: 'Portland',
  countryCode: 'US'
});

getConditions()

Retrieve current weather conditions for a specified city.

Signature:

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

Parameters:

  • params - Weather request parameters

WeatherConditionsParams:

type WeatherConditionsParams = {
  cityId: number;      // WeatherBit city ID (required)
  language?: string;   // Language code for localized responses
}

Returns: Promise<WeatherConditions> - Current weather conditions with dual units

Example:

const conditions = await weather.getConditions({ cityId: 5128581 });

// Access both unit systems
console.log(`Temperature: ${conditions.temperatureC}°C / ${conditions.temperatureF}°F`);
console.log(`Wind: ${conditions.windSpeedKph} km/h / ${conditions.windSpeedMph} mph`);
console.log(`Conditions: ${conditions.weatherDescription}`);

getDailyForecast()

Retrieve daily weather forecast for a specified city.

Signature:

async getDailyForecast(params: DailyForecastParams): Promise<DailyForecast>

Parameters:

  • params - Forecast request parameters

DailyForecastParams:

type DailyForecastParams = {
  cityId: number;      // WeatherBit city ID (required)
  language?: string;   // Language code for localized responses
  days?: number;       // Number of days to forecast (default: 5, max: 16)
}

Returns: Promise<DailyForecast> - Daily forecast with location and data array

Example:

const forecast = await weather.getDailyForecast({
  cityId: 5128581,
  days: 7
});

// Access location info
console.log(`Forecast for ${forecast.cityName}, ${forecast.stateName}`);

// Iterate through forecast days
forecast.data.forEach(day => {
  console.log(`${day.forecastDate}: ${day.weatherDescription}`);
  console.log(`  High: ${day.maxTemperatureC}°C / ${day.maxTemperatureF}°F`);
  console.log(`  Low: ${day.minTemperatureC}°C / ${day.minTemperatureF}°F`);
  console.log(`  Precipitation: ${day.precipitationProbability}%`);
});

getHourlyForecast()

Retrieve hourly weather forecast for a specified city.

Signature:

async getHourlyForecast(params: HourlyForecastParams): Promise<HourlyForecast>

Parameters:

  • params - Forecast request parameters

HourlyForecastParams:

type HourlyForecastParams = {
  cityId: number;      // WeatherBit city ID (required)
  language?: string;   // Language code for localized responses
  hours?: number;      // Number of hours to forecast (default: 12, max: 120)
}

Returns: Promise<HourlyForecast> - Hourly forecast with location and data array

Example:

const forecast = await weather.getHourlyForecast({
  cityId: 5128581,
  hours: 24
});

forecast.data.forEach(hour => {
  console.log(`${hour.forecastTimeLocal}: ${hour.temperatureC}°C`);
  console.log(`  ${hour.weatherDescription}`);
  console.log(`  Wind: ${hour.windSpeedKph} km/h ${hour.windDirectionShort}`);
});

getAlerts()

Retrieve severe weather alerts and warnings for a specified city.

Signature:

async getAlerts(params: WeatherAlertsParams): Promise<WeatherAlerts>

Parameters:

  • params - Alert request parameters

WeatherAlertsParams:

type WeatherAlertsParams = {
  cityId: number;      // WeatherBit city ID (required)
  language?: string;   // Language code for localized responses
}

Returns: Promise<WeatherAlerts> - Weather alerts with location information

Example:

const result = await weather.getAlerts({ cityId: 5128581 });

if (result.alerts.length > 0) {
  result.alerts.forEach(alert => {
    console.log(`[${alert.severity}] ${alert.title}`);
    console.log(`  Effective: ${alert.effectiveLocal}`);
    console.log(`  Expires: ${alert.expiresLocal}`);
    console.log(`  ${alert.description}`);
  });
} else {
  console.log('No active weather alerts');
}

Types

Type Aliases

type WeatherPartOfDay = 'day' | 'night';
type WeatherAlertSeverity = 'Advisory' | 'Watch' | 'Warning';

WeatherCity

City information returned from getCities().

type WeatherCity = {
  cityId: number;        // WeatherBit city ID (use for weather queries)
  cityName: string;      // City name
  stateName?: string;    // Full state/province name
  stateCode?: string;    // US only: state abbreviation (e.g., "WA")
  countryName: string;   // Full country name
  countryCode: string;   // ISO country code
  latitude: number;      // Latitude
  longitude: number;     // Longitude
}

WeatherConditions

Current weather conditions returned from getConditions().

type WeatherConditions = {
  // Location
  latitude: number;
  longitude: number;
  cityName: string;
  stateName?: string;
  stateCode?: string;       // US only
  countryName: string;
  countryCode: string;
  timezone: string;         // IANA timezone

  // Time
  observedAtSec: number;    // Unix timestamp of observation
  observedAtLocal: string;  // Local time with offset (e.g., "2025-01-15T14:30:00-08:00")
  sunrise: string;          // Local sunrise time (e.g., "07:23")
  sunset: string;           // Local sunset time (e.g., "17:45")
  partOfDay: WeatherPartOfDay;  // 'day' | 'night'

  // Weather
  weatherCode: number;         // See weather codes reference below
  weatherDescription: string;
  weatherIcon: string;

  // Temperature (dual-unit)
  temperatureC: number;
  temperatureF: number;
  temperatureFeelsLikeC: number;
  temperatureFeelsLikeF: number;
  dewPointC: number;
  dewPointF: number;

  // Wind (dual-unit)
  windSpeedKph: number;
  windSpeedMph: number;
  gustSpeedKph: number;
  gustSpeedMph: number;
  windDirectionDeg: number;
  windDirectionFull: string;   // e.g., "North-Northwest"
  windDirectionShort: string;  // e.g., "NNW"

  // Atmospheric (dual-unit)
  pressureMb: number;
  pressureInHg: number;
  seaLevelPressureMb: number;
  seaLevelPressureInHg: number;
  visibilityKm: number;
  visibilityMi: number;
  humidity: number;            // Relative humidity (%)
  clouds: number;              // Cloud coverage (%)

  // Precipitation (dual-unit)
  precipitationRateMmph: number;   // mm/hr
  precipitationRateInph: number;   // in/hr
  snowfallRateMmph: number;        // mm/hr
  snowfallRateInph: number;        // in/hr

  // Indices
  uvIndex: number;
  airQualityIndex: number;
}

DailyForecast

Daily forecast returned from getDailyForecast().

type DailyForecast = {
  // Location (same as WeatherConditions)
  latitude: number;
  longitude: number;
  cityName: string;
  stateName?: string;
  stateCode?: string;
  countryName: string;
  countryCode: string;
  timezone: string;

  // Forecast data
  data: DailyForecastData[];
}

DailyForecastData

Single day of forecast data.

type DailyForecastData = {
  // Date
  forecastDate: string;      // YYYY-MM-DD format
  forecastDateSec: number;   // Unix timestamp (midnight local)

  // Weather
  weatherCode: number;
  weatherDescription: string;
  weatherIcon: string;
  precipitationProbability: number;  // Percentage (0-100)

  // Temperature (dual-unit)
  temperatureC: number;              // Average
  temperatureF: number;
  maxTemperatureC: number;
  maxTemperatureF: number;
  minTemperatureC: number;
  minTemperatureF: number;
  highTemperatureC: number;          // Daytime high
  highTemperatureF: number;
  lowTemperatureC: number;           // Nighttime low
  lowTemperatureF: number;
  maxTemperatureFeelsLikeC: number;
  maxTemperatureFeelsLikeF: number;
  minTemperatureFeelsLikeC: number;
  minTemperatureFeelsLikeF: number;
  dewPointC: number;
  dewPointF: number;

  // Wind (dual-unit)
  windSpeedKph: number;
  windSpeedMph: number;
  gustSpeedKph: number;
  gustSpeedMph: number;
  windDirectionDeg: number;
  windDirectionFull: string;
  windDirectionShort: string;

  // Atmospheric (dual-unit)
  pressureMb: number;
  pressureInHg: number;
  seaLevelPressureMb: number;
  seaLevelPressureInHg: number;
  visibilityKm: number;
  visibilityMi: number;
  humidity: number;
  clouds: number;

  // Precipitation (dual-unit)
  precipitationMm: number;
  precipitationIn: number;
  snowfallMm: number;
  snowfallIn: number;
  snowDepthMm: number;
  snowDepthIn: number;

  // Indices
  uvIndex: number;

  // Moon/Sun
  sunrise: string;           // Local time (e.g., "07:23")
  sunset: string;
  moonrise: string;
  moonset: string;
  moonIllumination: number;  // 0-1 fraction
  moonLunationPhase: number; // 0=New, 0.5=Full
}

HourlyForecast

Hourly forecast returned from getHourlyForecast().

type HourlyForecast = {
  // Location (same as WeatherConditions)
  latitude: number;
  longitude: number;
  cityName: string;
  stateName?: string;
  stateCode?: string;
  countryName: string;
  countryCode: string;
  timezone: string;

  // Forecast data
  data: HourlyForecastData[];
}

HourlyForecastData

Single hour of forecast data.

type HourlyForecastData = {
  // Time
  forecastTimeSec: number;     // Unix timestamp
  forecastTimeLocal: string;   // Local time with offset
  forecastTimeUtc: string;     // UTC time with Z suffix
  partOfDay: WeatherPartOfDay;  // 'day' | 'night'

  // Weather
  weatherCode: number;
  weatherDescription: string;
  weatherIcon: string;
  precipitationProbability: number;

  // Temperature (dual-unit)
  temperatureC: number;
  temperatureF: number;
  temperatureFeelsLikeC: number;
  temperatureFeelsLikeF: number;
  dewPointC: number;
  dewPointF: number;

  // Wind (dual-unit)
  windSpeedKph: number;
  windSpeedMph: number;
  gustSpeedKph: number;
  gustSpeedMph: number;
  windDirectionDeg: number;
  windDirectionFull: string;
  windDirectionShort: string;

  // Atmospheric (dual-unit)
  pressureMb: number;
  pressureInHg: number;
  seaLevelPressureMb: number;
  seaLevelPressureInHg: number;
  visibilityKm: number;
  visibilityMi: number;
  humidity: number;
  clouds: number;

  // Precipitation (dual-unit)
  precipitationMm: number;
  precipitationIn: number;
  snowfallMm: number;
  snowfallIn: number;
  snowDepthMm: number;
  snowDepthIn: number;

  // Indices
  uvIndex: number;
}

WeatherAlerts

Weather alerts returned from getAlerts().

type WeatherAlerts = {
  // Location (same as WeatherConditions)
  latitude: number;
  longitude: number;
  cityName: string;
  stateName?: string;
  stateCode?: string;
  countryName: string;
  countryCode: string;
  timezone: string;

  // Alerts
  alerts: WeatherAlert[];
}

WeatherAlert

Single weather alert.

type WeatherAlert = {
  title: string;
  description: string;
  severity: WeatherAlertSeverity;  // 'Advisory' | 'Watch' | 'Warning'

  // Effective time (when issued)
  effectiveSec: number;
  effectiveUtc: string;
  effectiveLocal: string;

  // Expires time
  expiresSec: number;
  expiresUtc: string;
  expiresLocal: string;

  // Onset time (optional - when event starts)
  onsetSec?: number;
  onsetUtc?: string;
  onsetLocal?: string;

  // Ends time (optional - when event ends)
  endsSec?: number;
  endsUtc?: string;
  endsLocal?: string;

  uri: string;               // Link for more information
  regions: string[];         // Affected regions
}

Weather Codes Reference

The weatherCode field in responses corresponds to WeatherBit condition codes. For a complete list of codes and their meanings, see the WeatherBit API Codes Reference.

Usage Example

Complete example showing the typical workflow:

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

// 1. Search for a city to get its cityId
const cities = await weather.getCities({ search: 'Seattle', countryCode: 'US' });
const seattle = cities[0];
console.log(`Found: ${seattle.cityName}, ${seattle.stateName} (ID: ${seattle.cityId})`);

// 2. Get current conditions
const conditions = await weather.getConditions({ cityId: seattle.cityId });
console.log(`\nCurrent conditions in ${conditions.cityName}:`);
console.log(`  ${conditions.temperatureC}°C / ${conditions.temperatureF}°F`);
console.log(`  ${conditions.weatherDescription}`);
console.log(`  Humidity: ${conditions.humidity}%`);

// 3. Get daily forecast
const dailyForecast = await weather.getDailyForecast({
  cityId: seattle.cityId,
  days: 5
});
console.log(`\n5-Day Forecast:`);
dailyForecast.data.forEach(day => {
  console.log(`  ${day.forecastDate}: ${day.maxTemperatureC}°C / ${day.minTemperatureC}°C`);
});

// 4. Check for weather alerts
const alertsResult = await weather.getAlerts({ cityId: seattle.cityId });
if (alertsResult.alerts.length > 0) {
  console.log(`\nActive Alerts:`);
  alertsResult.alerts.forEach(alert => {
    console.log(`  [${alert.severity}] ${alert.title}`);
  });
}

Next Steps

Updated 26 days ago

What’s Next