Open Weather Client

Welcome to Open Weather Client. This gem allows you to easily request weather information from Open Weather. It integrates in your rails project, when you are using bundler or even in plain ruby projects.

Installation

Add this line to your application's Gemfile:

gem 'open_weather_client'

And then execute:

$ bundle

Or install it yourself as:

$ gem install open_weather_client

Usage

During configuration the Open Weather API key must be set. Afterwards it is as simple as calling OpenWeatherClient.current(lat:, lon:) to get the current weather at a location.

# OpenWeatherClient initializer
OpenWeatherClient.configure do |config|
  config.appid = "1234567890"
end

# Receive the current weather in Koblenz
OpenWeatherClient::Weather.current(lat: 50.3569, lon: 7.5890)

Used Open Weather API version

Open Weather provides One Call API 3.0 and API 2.5, which is expected to be deprecated in June 2024. Until API 2.5 is deprecated it is the default. With Open Weather Client version 1.0 the default will change to One Call API 3.0.

The used API version is configurable through OpenWeatherClient.configuration.api_version.

# OpenWeatherClient initializer
OpenWeatherClient.configure do |config|
  config.api_version = :v25 # (default) also supports :v30
end

Exceptions during requests

When an error occurs during a request, an exception is raised.

If the configured API version is not supported by the client, OpenWeatherClient::APIVersionNotSupportedError is raised. If the request is not authorized, OpenWeatherClient::AutheniticationError is raised. If attributes like latitude or longitude are outside of the expected range, RangeError is raised. If the time is longer in the past than one hour, OpenWeatherClient::NotCurrentError is raised.

Secure Configuration

Rails provides the credentials functionality for environmental security. This mechanism can be used by OpenWeatherClient to load the API key from an encrypted file. This also allows easy separation of production and development api key configuration.

All settings are defined under the top-level entry open_weather_client.

# $ bin/rails credentials:edit
open_weather_client:
  appid: "<INSERT OPENWEATHERMAP API KEY HERE>"

After configuring the credentials, they can be loaded in the initializer with #load_from_rails_configuration.

# OpenWeatherClient initializer
OpenWeatherClient.configure do |config|
  config.load_from_rails_credentials
end

Caching

By default Open Weather Client does not cache any data and every request will be send to the OpenWeatherMap servers.

To speed up requests and reduce the number network requests caching can be enabled. When Open Weather Client is reset, the cache is also reset. The cache may be accessed directly through the singleton OpenWeatherClient.cache.

Whether requests are only performed when the requested time is within the last hour. If caching is enabled, requests with a time older than one hour might still be answered with a response.

# OpenWeatherClient initializer
OpenWeatherClient.configure do |config|
  config.caching = OpenWeatherClient::Caching::Memory
  config.max_memory_entries = 100 # Maximum number of entries in memory cache
end

Cache key

The cache key for a given latitute, longitude and time is calculated by OpenWeatherClient::Caching#cache_key(lat, lon, time).

Memory Caching

OpenWeatherClient supports simple in memory caching. A hash is used to store and look up the cached responses.

Custom Caching

To implement custom caching, the interface of OpenWeatherClient::Caching is used. A custom caching solution must implement its specific caching_get(key), caching_store(key, data) and present?(key) methods.

Spatial Quantization

Since weather is more often than not a wider phenomenon, the high resolution location data, commonly available today may interfere with the performance even when using caching. Caching uses the full resolution of the location data. By default no quantization is performed.

OpenWeatherClient allows defining a quantization function to transform the latitude and longitude data before making requests or hitting the cache. The quantization receives latitude and longitude. The result is coerced back into latitude and longitude.

# OpenWeatherClient initializer
OpenWeatherClient.configure do |config|
  config.spatial_quantization = proc { |lat, lon| [lat.round(2), lon.round(2)] }
end

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

You can define the client settings you use for testing in the file bin/config.yml or directly in the bin/console script.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/qurasoft/open_weather_client. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

License

The gem is available as open source under the terms of the MIT License.