Skip to content
🌦 An implementation to easily fetch the OpenWeatherMap API
Ruby
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github
lib
.gitignore
LICENSE
README.md
openweathermap.gemspec

README.md

OpenWeatherMap - The Ruby implementation

With this gem, you can easily fetch the API to receive informations about weather.

License - RubyDoc

Why would I use this library ?

Before writing this OpenWeatherMap implementation, I checked for existing ones on rubygems.org. There's only small libraries, that has at least one or two good thing but that's all. Consequently, I decided to make my own one, combining all their advantages :

  • Centralized : all the options and fetch methods are stored in one class, that is initialized only once in all the program. Parameters are the same across all requests.
  • Fast : the only thing that can slow the library is your Internet connection : indeed, no heavy operations are made in the background. As soon as it receives weather conditions, the only step for it is organizing them.
  • Simple : the library only contains essential operations to keep the number of methods low. Moreover, all the information is perfectly human-readable.
  • Documented : every method and class attribute is explained and every exception thrown is explicit, therefore learning or debugging the library remains easy.

This work resulted in a powerful implementation that responds to primary needs while staying abordable.

πŸ“Œ Requirements

This library requires an updated version of Ruby.

πŸ”§ Setup

Quick installation

If you want to quickly test the library, you can install it using the install command of Ruby Gem.

gem install openweathermap

Gemfile

If you setup the library for medium or big projects, it's recommended to write it in your Gemfile.

gem 'openweathermap', '~> 0.2.3'

After, use again the install command, but without the package name.

gem install

Build

You can also compile it by yourself. First, clone the repository.

git clone https://github.com/BecauseOfProg/openweathermap-ruby.git  # HTTP
          git@github.com:BecauseOfProg/openweathermap-ruby.git      # SSH

Then, build the gemspec file to create the gem.

gem build ./openweathermap.gemspec

Finally, install it on your system.

gem install ./openweathermap-0.2.3.gem

⌨ Basic interactions

Once you finished installing the library, you're ready to play around.

Setup the API

First of all, include the openweathermap library in your project :

include 'openweathermap'

Then, we must initialize an API object in the OpenWeatherMap module, that we'll use to get our weather data.

api = OpenWeatherMap::API.new(API_KEY, 'en', 'metric')

The constructor takes three parameters :

  • The first is an API key, that can be generated on the OpenWeatherMap website
  • The second is the language of the data. It can be one of these : Arabic - ar, Bulgarian - bg, Catalan - ca, Czech - cz, German - de, Greek - el, English - en, Persian (Farsi) - fa, Finnish - fi, French - fr, Galician - gl, Croatian - hr, Hungarian - hu, Italian - it, Japanese - ja, Korean - kr, Latvian - la, Lithuanian - lt, Macedonian - mk, Dutch - nl, Polish - pl, Portuguese - pt, Romanian - ro, Russian - ru, Swedish - se, Slovak - sk, Slovenian - sl, Spanish - es, Turkish - tr, Ukrainian - ua, Vietnamese - vi, Chinese Simplified - zh_cn, Chinese Traditional - zh_tw.
  • The third is the unit system. It can be one of these :
    • default (temperatures in Kelvin)
    • metric (temperatures in Celsius)
    • imperial (temperatures in Fahrenheit)

Get current weather

To get the current weather at a certain city anywhere in the world, use the current method of the API object :

api.current('Lyon,FR')

It only takes one parameter : the location. It can be one of this type :

  • A simple string : search by city name. To have more precision, it can be completed with the country code separated by a comma
  • An integer : search by city ID (refer to OpenWeatherMap)
  • An array : search by coordinates (format : [longitude, latitude])

The method will return a OpenWeatherMap::CurrentWeather object that you can explore on RubyDoc.

Get forecast

To get the forecast for a certain city anywhere in the world, use the forecast method of the API object :

api.forecast('Paris,FR')

Its parameter is the same as the current method. It will return a OpenWeatherMap::Forecast object that you can explore on RubyDoc.

Possible exceptions

Your requests may return exceptions that are in the OpenWeatherMap::Exceptions module. All are based on the OpenWeatherMap::Exception class.

  • An Unauthorized exception, caused when your API key is wrong
  • An UnknownLocation exception, caused if the location you wrote is wrong

These exceptions will have in their body the message sent by the OpenWeatherMap API, so you can easily debug them.

πŸ“œ Credits

πŸ” License

MIT License

Copyright (c) 2019 BecauseOfProg

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

You can’t perform that action at this time.