OpenWeatherMap.API 4.0.1-pre

OpenWeatherMap.API

OpenWeatherMap API client for .NET

Download and Install OpenWeatherMap.API

This library is available on NuGet: https://www.nuget.org/packages/OpenWeatherMap.API Use the following command to install OpenWeatherMap.API using NuGet package manager console:

PM> Install-Package OpenWeatherMap.API

You can use this library in any .NET project which is compatible to .NET Standard 2.0 and higher.

Supported APIs

An API key is required for all API methods. Some API methods require a paid OpenWeatherMap subscription.

API Usage

The following sections document basic use cases of this library. The following code excerpts can also be found in the sample applications.

Create weather service

OpenWeatherMapService is the main entry point of this library. Create an instance of OpenWeatherMapService or inject IOpenWeatherMapService using dependency injection techniques.

var openWeatherMapOptions = new OpenWeatherMapOptions
{
    ApiKey = "<-INSERT-YOUR-API-KEY-HERE->",
    UnitSystem = UnitSystem.Metric,
    Language = "en",
};

IOpenWeatherMapService openWeatherMapService = new OpenWeatherMapService(logger, openWeatherMapOptions);

If you use Microsoft.Extensions.DependencyInjection, register IOpenWeatherMapService with AddOpenWeatherMap. The options can be bound to a configuration section (e.g. from appsettings.json) or configured in code:

serviceCollection.AddOpenWeatherMap(configuration.GetSection("OpenWeatherMap"));

{
  "OpenWeatherMap": {
    "ApiKey": "<-INSERT-YOUR-API-KEY-HERE->",
    "UnitSystem": "metric",
    "Language": "en"
  }
}

Request current weather for GPS position

Call GetCurrentWeatherAsync with latitude and longitude to retrieve the current weather information for the given location. WeatherInfo is the model that contains all relevant information provided by OpenWeatherMap API.

var weatherInfo = await openWeatherMapService.GetCurrentWeatherAsync(latitude: 47.1823761d, longitude: 8.4611036d);

Console.WriteLine(
    $"Current Weather Info:{Environment.NewLine}" +
    $"Location: {weatherInfo.CityName}{Environment.NewLine}" +
    $"Temperature: {weatherInfo.Main.Temperature}{Environment.NewLine}" +
    $"Humidity: {weatherInfo.Main.Humidity}{Environment.NewLine}" +
    $"Pressure: {weatherInfo.Main.Pressure}{Environment.NewLine}");

Request 5 day / 3 hour forecast

var weatherForecast = await openWeatherMapService.GetWeatherForecast5Async(latitude, longitude, count: 8);

foreach (var forecastItem in weatherForecast.Items)
{
    Console.WriteLine($"{forecastItem.DateTime.ToLocalTime():g}: {forecastItem.Main.Temperature}");
}

Request weather data using One Call API 4.0

One Call API 4.0 provides current weather, a minute forecast for 1 hour, a 15 minutes forecast for 48 hours, an hourly timeline (history since 1979 and forecast for 48 hours), a daily timeline (history since 1979 and forecast for 1.5 years) and national weather alerts. It requires a "One Call by Call" subscription for One Call API 4.0; requests without this subscription fail with HTTP 401 (Unauthorized).

All One Call API 4.0 methods return a OneCallTimeline<T> with the weather records in property Data.

var currentTimeline = await openWeatherMapService.GetWeatherOneCallCurrentAsync(latitude, longitude);
var currentWeather = currentTimeline.Data.Single();

var dailyTimeline = await openWeatherMapService.GetWeatherOneCallDailyAsync(latitude, longitude);
foreach (var dailyForecast in dailyTimeline.Data)
{
    Console.WriteLine($"{dailyForecast.DateTime:d}: {dailyForecast.Temperature.Min}/{dailyForecast.Temperature.Max}");
}

The timelines are paginated. Request the previous or next page of a timeline with GetWeatherOneCallPreviousPageAsync and GetWeatherOneCallNextPageAsync (each page is billed as a separate API call). Historical data is requested by passing a start date:

// Hourly weather data of 2020-03-04, starting at 00:00 UTC
var hourlyTimeline = await openWeatherMapService.GetWeatherOneCallHourlyAsync(latitude, longitude, start: new DateTime(2020, 3, 4, 0, 0, 0, DateTimeKind.Utc));
var nextPage = await openWeatherMapService.GetWeatherOneCallNextPageAsync(hourlyTimeline); // null if there is no next page

Weather records reference weather alerts by ID. Use GetWeatherOneCallAlertAsync to get the details of an alert:

foreach (var alertId in currentWeather.Alerts)
{
    var alertInfo = await openWeatherMapService.GetWeatherOneCallAlertAsync(alertId);
    Console.WriteLine($"{alertInfo.SenderName}: {alertInfo.EventName}");
}

Find locations using the Geocoding API

// Coordinates by location name (city name, state code (US only), country code)
var locations = await openWeatherMapService.GetLocationsByNameAsync("Menznau,CH", limit: 1);

// Coordinates by zip/post code
var zipCodeLocation = await openWeatherMapService.GetLocationByZipCodeAsync("6122", "CH");

// Location names by coordinates (reverse geocoding)
var nearbyLocations = await openWeatherMapService.GetLocationsByCoordinatesAsync(latitude, longitude);

Request air pollution data

var airPollutionInfo = await openWeatherMapService.GetAirPollutionAsync(latitude, longitude);
var airPollutionForecast = await openWeatherMapService.GetAirPollutionForecastAsync(latitude, longitude);
var airPollutionHistory = await openWeatherMapService.GetAirPollutionHistoryAsync(latitude, longitude, start: DateTime.UtcNow.AddDays(-1), end: DateTime.UtcNow);

Migrating from 2.x to 4.0

OpenWeatherMap retired One Call API 2.5. Version 4.0 of this library migrates to One Call API 4.0 and contains the following breaking changes:

Further breaking changes:

• UnitSystem.Standard returns temperatures in Kelvin (as provided by OpenWeatherMap) instead of Celsius.
• IOpenWeatherMapService has new members. Custom implementations of this interface need to be extended.
• CurrentWeatherForecast.Rain and CurrentWeatherForecast.Snow are nullable since they are only provided if available.

Contribution

Contributors welcome! If you find a bug or you want to propose a new feature, feel free to do so by opening a new issue on github.com.

License

This project is Copyright © 2026 Thomas Galliker. Free for non-commercial use. For commercial use please contact the author.