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're 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
• 🔧 Setup
  • Quick installation
  • Gemfile
  • Build
• ⌨ Basic interactions
  • Setup the API
  • Get current weather
  • Get forecast
  • Possible exceptions
• 📜 Credits
• 🔐 License

📌 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

• Used service : OpenWeatherMap
• Maintainer : Théo Vidal (exybore)

🔐 License

See License file