fuel_prices_europe

Fuel Prices Europe

This Ruby gem scrapes the average European fuel prices from fuel-prices-europe.info. The following data can be found for each country:

• Price of unleaded 95 RON in euros (and in local currency if available)
• Price of diesel in euros (and in local currency if available)
• Price of LPG in euros (and in local currency if available)
• LPG nozzle type
• Number of LPG stations
• Recording date of the data

See Usage for all functions.

Installation

Add this line to your application's Gemfile:

gem 'fuel_prices_europe'

And then execute:

$ bundle

Or install it yourself as:

$ gem install fuel_prices_europe

Configuration

A configuration is optional, however I strongly recommend using the cache option to avoid making too much requests to the source website. Example configuration with explanation in the comments:

FuelPricesEurope.configure do |config|
  # It is recommended to use a cache. Fuel prices will only be updated once a day.
  # Leave this out of the configuration to not use the cache.
  # This must be a cache object (with read, write and fetch methods).
  config.cache = Rails.cache

  # If you are using the cache you can set a custom cache key.
  # Default value: fuel-prices-europe_data
  # config.cache_prefix = 'your_own_key'

  # Duration of how long data should be cached. Example: 24.hours
  # It is recommended it cache for 24 hours, because fuel prices are updated once a day on the source website.
  # Default value: 86400 (24.hours)
  config.cache_expires_in = 24.hours
end

If you are using Rails, add the configuration to a file (fuel_prices_europe.rb) in your config/initializers folder.

Usage

Find data by country

You can find by country. There are three methods you can use:

1. Find by alpha2 country code: find_by_country_code(country_code) (alias for: find_by_country_alpha2)
2. Find by alpha3 country code: find_by_country_alpha3(country_code)
3. Find by country name: find_by_country_name(country_name)

Important: If possible, use the method 1 for the best performance. Methods 2 and 3 will convert the input argument to an alpha2 code using the Countries gem. Methods 2 and 3 should be used if you do not have the alpha2 country code.

All the above methods will return a CountryData object. The CountryData methods are shown in the examples below.

Examples

Example #1: Uses a country which has all data except local prices.

fuel_prices = FuelPricesEurope::FuelPrices.new
country_data = fuel_prices.find_by_country_code('NL') #=> CountryData.new

country_data.country #=> Country.new('NL')
country_data.record_date #=> DateTime.new(2015, 2, 7)
country_data.lpg_stations #=> 1945
country_data.lpg_nozzle #=> 'bayonet'
country_data.lpg_price #=> 0.769
country_data.lpg_price_local #=> nil
country_data.diesel_price #=> 1.297
country_data.diesel_price_local #=> nil
country_data.unleaded_95_ron_price #=> 1.579
# Alias method for unleaded_95_ron_price: gasoline_price
country_data.unleaded_95_ron_price_local #=> nil
# Alias method for unleaded_95_ron_price_local: gasoline_price_local

Example #2: This country has local prices:

fuel_prices = FuelPricesEurope::FuelPrices.new
country_data = fuel_prices.find_by_country_name('Lebanon') #=> CountryData.new

country_data.diesel_price_local #=> {:currency => 'LBP', :value => 1410.0}
country_data.lpg_price_local #=> {:currency => 'LBP', :value => 1170.0}
country_data.unleaded_95_ron_price_local #=> {:currency => 'LBP', :value => 2110.0}
country_data.lpg_stations #=> nil
country_data.lpg_nozzle #=> nil

The country method will return a Country object. This Country object comes from the Countries gem.

Find data by multiple countries

You can use the find_by_countries(countries, type = :alpha2) method to find for multiple countries. By default you have to pass in an array of alpha2 country codes. Using alpha2 codes is recommended. But you can also by specifying a type with the second argument, valid types are :alpha2, :alpha3 and :name

An example:

fuel_prices = FuelPricesEurope::FuelPrices.new
countries_data = fuel_prices.find_by_countries(['NL', 'BE']) #=> {'NL' => CountryData.new, 'BE' => CountryData.new}

countries_data['NL'].gasoline_price #=> 1.579

The method returns a hash with CountryData objects with the input countries as keys.

Notes

All countries have prices in euros. If you need the local prices, you can use the _local methods. Only countries that have a local currency will return data. The price and currency will be return. See example #2

Thera are three possible nozzle types: bayonet, acme and dish

nil will be returned if the source website has no information. The applies to the following:

• If lpg_nozzle is unknown.
• If lpg_stations is unknown.
• If lpg_price_local has no value.
• If unleaded_96_ron_price_local has no value.
• If diesel_price_local has no value.

0.0 will be returned if a the euro price for lpg_price, unleaded_95_ron and diesel_price is not found.

Contributing

1. Fork it ( https://github.com/[my-github-username]/fuel_prices_europe/fork )
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create a new Pull Request