👁 Image
Xcalibur.Weather.Helpers 1.0.7

Xcalibur.Weather.Helpers

👁 .NET Version
👁 NuGet

A comprehensive .NET helper library providing utility functions for weather-related operations. Includes conversion helpers for temperature, wind speed, length, and pressure, along with specialized helpers for Open-Meteo, Geocodio, IpGeolocation.io, Atmospore, SunriseSunset.io, OpenStreetMap, and combined weather alert operations (Meteoalarm, NWS, GDACS, Environment Canada, BOM, EMSC, DWD).

Created by: Joshua Arzt | Company: Xcalibur Systems, LLC.

📋 Table of Contents

• Features
  • Conversion Utilities
  • Weather Service Helpers
• Installation
• Requirements
• Usage
  • Temperature Conversion
  • Wind Speed Conversion
  • Length Conversion
  • Pressure Conversion
  • OpenMeteo Helper
  • Geocodio Helper
  • IpGeolocation Helper
  • Atmospore Helper
  • SunriseSunset Helper
  • OpenStreetMap Helper
  • Weather Alert Helper
  • Weather Region Helper
• API Overview
• Best Practices
• Testing
• Dependencies
• License
• Related Projects

Features

Conversion Utilities

• Temperature Conversion: Celsius ↔ Fahrenheit conversions with formatting options
• Wind Speed Conversion: Convert between km/h, mph, ft/s, m/s, and knots
• Length Conversion: Convert between millimeters and inches
• Pressure Conversion: Convert between hPa, inHg, and mmHg
• Smart Formatting: Format values with or without unit symbols

Weather Service Helpers

• OpenMeteoHelper: Build air quality points, current forecasts, hourly forecasts, daily forecasts, and yesterday's data
• GeocodioHelper: Test API keys, build address locations from geocoding queries
• IpGeoHelper: Build sun/moon points and test API connectivity for astronomical data
• AtmosporeHelper: Test API keys, retrieve pollen forecasts from the Atmospore API
• SunriseSunsetHelper: Fetch sunrise/sunset and astronomical data from SunriseSunset.io — no API key required
• OpenStreetMapHelper: Geocode addresses using the OpenStreetMap Nominatim API — no API key required
• WeatherAlertHelper: Build combined weather alert information from multiple global services (Meteoalarm, NWS, GDACS, Environment Canada, BOM, EMSC, DWD)
• WeatherRegionHelper: Determine geographic regions, check if coordinates are in Germany, determine Canadian provinces and Australian states

Installation

NuGet Package Manager

Install-Package Xcalibur.Weather.Helpers

.NET CLI

dotnet add package Xcalibur.Weather.Helpers

Package Reference

<PackageReference Include="Xcalibur.Weather.Helpers" Version="1.0.3" />

Requirements

• .NET 10 or later
• Xcalibur.Weather.Models (included as dependency)
• Microsoft.Extensions.Hosting (included as dependency)

Usage

Temperature Conversion

using Xcalibur.Weather.Helpers;
using Xcalibur.Weather.Models;

// Convert Celsius to Fahrenheit
double celsius = 25.0;
double fahrenheit = celsius.CelsiusToFahrenheit(); // 77.0

// Convert Fahrenheit to Celsius
double temp = 77.0;
double celsiusValue = temp.FahrenheitToCelsius(); // 25.0

// Format temperature with unit
string formatted = celsius.FormatTemperature(TemperatureUnits.Fahrenheit, includeUnit: true);
// Output: "77°F"

Wind Speed Conversion

using Xcalibur.Weather.Helpers;
using Xcalibur.Weather.Models;

// Convert wind speed from km/h to various units
double windSpeed = 100.0; // km/h

double mph = windSpeed.ConvertWindSpeed(WindSpeedUnits.Mph); // 62.14
double mps = windSpeed.ConvertWindSpeed(WindSpeedUnits.MSec); // 27.78
double knots = windSpeed.ConvertWindSpeed(WindSpeedUnits.Knots); // 53.99
double fps = windSpeed.ConvertWindSpeed(WindSpeedUnits.FtSec); // 91.13

Length Conversion

using Xcalibur.Weather.Helpers;
using Xcalibur.Weather.Models;

// Format precipitation in different units
double? precipitation = 25.4; // millimeters

string metric = precipitation.FormatLength(DistanceUnits.Metric, includeUnit: true);
// Output: "25.40 mm"

string imperial = precipitation.FormatLength(DistanceUnits.Imperial, includeUnit: true);
// Output: "1.00 in"

Pressure Conversion

using Xcalibur.Weather.Helpers;
using Xcalibur.Weather.Models;

// Format atmospheric pressure in different units
double? pressure = 1013.25; // hectopascals

string hPa = pressure.FormatPressure(BarometerUnits.HPa, includeUnit: true);
// Output: "1013.25 hPa"

string inHg = pressure.FormatPressure(BarometerUnits.InHg, includeUnit: true);
// Output: "29.92 inHg"

string mmHg = pressure.FormatPressure(BarometerUnits.MmHg, includeUnit: true);
// Output: "760.00 mmHg"

OpenMeteo Helper

using Xcalibur.Weather.Helpers.Services;
using Microsoft.Extensions.Logging;

// Build air quality data point
var airQuality = await OpenMeteoHelper.BuildAirQualityPointAsync(
 latitude: "40.7128",
 longitude: "-74.0060",
 logger: logger,
 cancellationToken: CancellationToken.None
);

// Build current weather forecast
var currentForecast = await OpenMeteoHelper.BuildCurrentForecastAsync(
 latitude: "40.7128",
 longitude: "-74.0060",
 canAssessDayNight: true,
 sunrise: new TimeOnly(6, 30),
 sunset: new TimeOnly(18, 30),
 logger: logger,
 cancellationToken: CancellationToken.None
);

// Build hourly forecast
var hourlyForecast = await OpenMeteoHelper.BuildHourlyForecastAsync(
 latitude: "40.7128",
 longitude: "-74.0060",
 canAssessDayNight: true,
 sunrise: new TimeOnly(6, 30),
 sunset: new TimeOnly(18, 30),
 logger: logger,
 cancellationToken: CancellationToken.None
);

// Build daily forecast
var dailyForecast = await OpenMeteoHelper.BuildDailyForecastAsync(
 latitude: "40.7128",
 longitude: "-74.0060",
 forecastDays: 7,
 logger: logger,
 cancellationToken: CancellationToken.None
);

// Build yesterday's hourly forecast
var yesterdayHourlyForecast = await OpenMeteoHelper.BuildYesterdayHourlyForecastAsync(
 latitude: "40.7128",
 longitude: "-74.0060",
 canAssessDayNight: true,
 sunrise: new TimeOnly(6, 30),
 sunset: new TimeOnly(18, 30),
 logger: logger,
 cancellationToken: CancellationToken.None
);

// Build yesterday's daily forecast
var yesterdayDailyForecast = await OpenMeteoHelper.BuildYesterdayDailyForecastAsync(
 latitude: "40.7128",
 longitude: "-74.0060",
 logger: logger,
 cancellationToken: CancellationToken.None
);

Geocodio Helper

using Xcalibur.Weather.Helpers.Services;
using Microsoft.Extensions.Logging;

// Test Geocodio API key
bool isValid = await GeocodioHelper.TestApiKeyAsync(
 apiKey: "your-api-key",
 logger: logger
);

// Build address locations from query
var locations = await GeocodioHelper.BuildAddressLocationsAsync(
 apiKey: "your-api-key",
 query: "1600 Pennsylvania Avenue NW, Washington, DC",
 country: "US",
 logger: logger
);

IpGeolocation Helper

using Xcalibur.Weather.Helpers.Services;
using Microsoft.Extensions.Logging;

// Test IpGeolocation API key
bool isValid = await IpGeoHelper.TestApiKeyAsync(
 apiKey: "your-api-key",
 logger: logger
);

// Build sun/moon astronomical data
var sunMoonData = await IpGeoHelper.BuildSunMoonPointAsync(
 ipGeoApiKey: "your-api-key",
 latitude: "40.7128",
 longitude: "-74.0060",
 logger: logger
);

Atmospore Helper

using Xcalibur.Weather.Helpers.Services;
using Microsoft.Extensions.Logging;

// Test Atmospore API key
bool isValid = await AtmosporeHelper.TestApiKeyAsync(
 apiKey: "your-api-key",
 logger: logger
);

// Build pollen forecast
var pollenForecast = await AtmosporeHelper.BuildPollenForecastAsync(
 apiKey: "your-api-key",
 latitude: "39.43",
 longitude: "-77.80",
 date: "2024-05-27", // Optional, defaults to today
 forecastDays: 1,
 logger: logger
);

if (pollenForecast is not null)
{
 Console.WriteLine($"Date: {pollenForecast.ForecastDate}");
 foreach (var entry in pollenForecast.Entries)
 {
 Console.WriteLine($"{entry.DisplayName}: {entry.RiskLevel}");
 }
}

SunriseSunset Helper

using Xcalibur.Weather.Helpers.Services;
using Microsoft.Extensions.Logging;

// Build sun/moon data — no API key required
var sunMoonData = await SunriseSunsetHelper.BuildSunMoonPointAsync(
 latitude: "40.7128",
 longitude: "-74.0060",
 logger: logger
);

OpenStreetMap Helper

using Xcalibur.Weather.Helpers.Services;
using Microsoft.Extensions.Logging;

// Geocode an address — no API key required
var locations = await OpenStreetMapHelper.BuildAddressLocationsAsync(
 query: "1600 Pennsylvania Avenue NW, Washington, DC",
 country: "US",
 logger: logger
);

Weather Alert Helper

using Xcalibur.Weather.Helpers.Services;
using Microsoft.Extensions.Logging;

// Build combined weather alerts from multiple sources
// (Meteoalarm, NWS, GDACS, Environment Canada, BOM, EMSC, DWD)
var alerts = await WeatherAlertHelper.BuildCombinedAlertsAsync(
 latitude: 52.52,
 longitude: 13.41,
 countryCode: "DE",
 logger: logger
);

if (alerts is not null && alerts.Alerts.Any())
{
 Console.WriteLine($"Active Alerts: {alerts.TotalAlerts}");
 foreach (var alert in alerts.Alerts)
 {
 Console.WriteLine($"[{alert.Severity}] {alert.Event}");
 Console.WriteLine($" Source: {alert.Source}");
 Console.WriteLine($" Effective: {alert.Effective}");
 Console.WriteLine($" Expires: {alert.Expires}");
 }
}

Weather Region Helper

using Xcalibur.Weather.Helpers.Services;

// Determine geographic region
var region = WeatherRegionHelper.DetermineRegion(
 latitude: 52.52,
 longitude: 13.41,
 countryCode: "DE"
);

Console.WriteLine($"Region: {region}"); // Output: Europe

// Check if coordinates are in Germany
bool isGermany = WeatherRegionHelper.IsInGermany(
 latitude: 52.52,
 longitude: 13.41
);

// Determine Canadian province
var province = WeatherRegionHelper.DetermineCanadianProvince(
 latitude: 43.65,
 longitude: -79.38
);

Console.WriteLine($"Province: {province}"); // Output: ON

// Determine Australian state
var state = WeatherRegionHelper.DetermineAustralianState(
 latitude: -33.87,
 longitude: 151.21
);

Console.WriteLine($"State: {state}"); // Output: NSW

API Overview

ConversionHelper

OpenMeteoHelper

GeocodioHelper

IpGeoHelper

AtmosporeHelper

SunriseSunsetHelper

OpenStreetMapHelper

WeatherAlertHelper

WeatherRegionHelper

Testing

The library ships with a comprehensive xUnit test suite covering all helpers and conversion utilities.

Test Coverage

Running the Tests

dotnet test

Or via the .NET CLI targeting the test project directly:

dotnet test Xcalibur.Weather.Helpers.Tests/Xcalibur.Weather.Helpers.Tests.csproj

Best Practices

Null Handling

All conversion methods include overloads that handle nullable values:

double? temperature = null;
double result = temperature.CelsiusToFahrenheit(defaultValue: 0); // Returns 0

Logging

All service helpers accept an ILogger parameter for diagnostics and troubleshooting:

using Microsoft.Extensions.Logging;

ILogger logger = loggerFactory.CreateLogger<YourClass>();
var forecast = await OpenMeteoHelper.BuildCurrentForecast(
 latitude, longitude, true, sunrise, sunset, logger
);

HttpClient Usage

Service helpers manage HttpClient usage internally, so callers can use the helper APIs directly without constructing provider service instances.

Dependencies

This library depends on:

• Xcalibur.Weather.Models - Weather data models
• Microsoft.Extensions.Hosting - Hosting abstractions

License

This project is licensed under the Apache License 2.0. See the file for details.

Copyright © 2006 - 2026, Xcalibur Systems, LLC - All Rights Reserved

Related Projects

• Xcalibur.Weather.Models - Core weather data models and DTOs (GitHub)
• Xcalibur.Weather.Services - HTTP client services for weather APIs (GitHub)

Part of the Xcalibur Weather ecosystem for comprehensive weather data integration.

Author

Joshua Arzt
Xcalibur Systems, LLC