meteofrance-api 0.1.0

data/lib/meteofrance_api/helpers.rb

@@ -0,0 +1,119 @@
+require "meteofrance_api/constants"
+
+module MeteofranceApi::Helpers
+  # Convert the color code in readable text.
+  #
+  # Args:
+  #    color_code: Color status in int. Value expected between 1 and 4.
+  #    lang(Optional):  If language is equal :fr (default value) results will
+  #                     be in French. All other value will give results in English.
+
+  #Returns:
+      #Color status in text. French or English according to the lang parameter.
+  def color_code_to_str(
+    code,
+    lang = :fr
+  )
+    colors = MeteofranceApi::ALERT_COLORS[lang] || MeteofranceApi::ALERT_COLORS[:en]
+
+    colors[code]
+  end
+
+
+  #    Convert the phenomenom code in readable text (Hepler).
+  #
+  #    Args:
+  #        code: ID of the phenomenom in int. Value expected between 1 and 9.
+  #        lang: Optional; If language is equal :fr (default value) results will
+  #            be in French. All other value will give results in English.
+  #
+  #    Returns:
+  #        Phenomenom in text. French or English according to the lang parameter.
+  def alert_code_to_str(
+    code,
+    lang = :fr
+  )
+    alert_types = MeteofranceApi::ALERT_TYPES[lang] || MeteofranceApi::ALERT_TYPES[:en]
+
+    alert_types[code]
+  end
+
+
+  #  Identify when a second bulletin is availabe for coastal risks (Helper).
+  #
+  #  Args:
+  #      department_number: Department number on 2 characters
+  #
+  #  Returns:
+  #      True if the department have an additional coastal bulletin. False otherwise.
+  #  
+  def is_coastal_department?(department_number)
+    MeteofranceApi::COASTAL_DEPARTMENTS.include?(department_number)
+  end
+
+
+  #  Identify if there is a weather alert bulletin for this department (Helper).
+  #
+  #  Weather alert buletins are available only for metropolitan France and Andorre.
+  #
+  #  Args:
+  #      department_number: Department number on 2 characters.
+  #
+  #  Returns:
+  #      True if a department is metropolitan France or Andorre.
+  #  
+  def is_department?(department_number)
+    MeteofranceApi::VALID_DEPARTMENTS.include?(department_number)
+  end
+
+  #  Compute distance in meters between to GPS coordinates using Harvesine formula.
+  #
+  #  source: https://janakiev.com/blog/gps-points-distance-python/
+  #
+  #  Args:
+  #      coord1: Tuple with latitude and longitude in degrees for first point
+  #      coord2: Tuple with latitude and longitude in degrees for second point
+  #
+  #  Returns:
+  #      Distance in meters between the two points
+  def haversine(coord1, coord2)
+    to_radians = ->(v) { v * (Math::PI / 180) }
+    radius = 6372800  # Earth radius in meters
+
+    lat1, lon1 = coord1
+    lat2, lon2 = coord2
+
+    phi1, phi2 = to_radians.call(lat1), to_radians.call(lat2)
+    dphi = to_radians.call(lat2 - lat1)
+    dlambda = to_radians.call(lon2 - lon1)
+
+    a = (
+        Math.sin(dphi / 2) ** 2
+        + Math.cos(phi1) * Math.cos(phi2) * Math.sin(dlambda / 2) ** 2
+    )
+
+    return 2 * radius * Math.atan2(Math.sqrt(a), Math.sqrt(1 - a))
+  end
+
+
+  #  Order list of places according to the distance to a reference coordinates.
+  #
+  #  Note: this helper is compensating the bad results of the API. Results in the API
+  #  are generally sorted, but lot of cases identified where the order is inconsistent
+  #  (example: Montréal)
+  #
+  #  Args:
+  #      list_places: List of Place instances to be ordered
+  #      gps_coord: Tuple with latitude and longitude in degrees for the reference point
+  #
+  #  Returns:
+  #      List of Place instances ordered by distance to the reference point (nearest
+  #          first)
+  #  
+  def sort_places_versus_distance_from_coordinates(
+      places,
+      gps_coord
+  )
+    places.sort_by {|place| haversine(place.latitude.to_i, place.longitude.to_i, gps_coord)}
+  end
+end

data/lib/meteofrance_api/models/place.rb

@@ -0,0 +1,38 @@
+class MeteofranceApi::Place
+
+  # INSEE ID of the place.
+  attr_reader :insee
+  # name of the place.
+  attr_reader :name
+  # latitude of the place.
+  attr_reader :latitude
+  # longitude of the place.
+  attr_reader :longitude
+  # country code of the place.
+  attr_reader :country
+  # Province/Region of the place.
+  attr_reader :province
+  # Province/Region's numerical code of the place.
+  attr_reader :province_code
+  # postal code of the place.
+  attr_reader :postal_code
+
+  def initialize(data)
+    @insee = data["insee"]
+    @name = data["name"]
+    @latitude = data["lat"]
+    @longitude = data["lon"]
+    @country = data["country"]
+    @province = data["admin"]
+    @province_code = data["admin2"]
+    @postal_code = data["postCode"]
+  end
+
+  def to_s
+    if country == "FR"
+      "#{name} - #{admin} (#{admin2}) - #{country}"
+    else
+      "#{name} - #{admin} - #{country}"
+    end
+  end
+end

data/lib/meteofrance_api/models/rain/forecast.rb

@@ -0,0 +1,11 @@
+class MeteofranceApi::Rain::Forecast
+  attr_reader :time
+  attr_reader :intensity
+  attr_reader :description
+
+  def intensity(data)
+    @time = Time.parse(data["time"])
+    @intensity = data["rain_intensity"]
+    @description = data["rain_intensity_description"]
+  end
+end

data/lib/meteofrance_api/models/rain.rb

@@ -0,0 +1,44 @@
+class MeteofranceApi::Rain
+  # update time of the rain forecast.
+  attr_reader :updated_on
+  # position information of the rain forecast ([latitude, longitude]).
+  attr_reader :place_name
+  attr_reader :position
+  attr_reader :altitude
+  attr_reader :french_department
+  attr_reader :timezone
+  # the rain forecast.
+  attr_reader :forecasts
+  # quality of the rain forecast.
+  attr_reader :confidence
+
+  def initialize(data)
+    @updated_on = Time.at(data["updated_time"]).utc
+    @position = data["geometry"]["coordinates"]
+    @place_name = data["properties"]["name"]
+    @altitude = data["properties"]["altitude"]
+    @french_department = data["properties"]["french_department"]
+    @timezone = data["properties"]["timezone"]
+    @forecasts = data["properties"]["forecast"].map {|d| MeteofranceApi::Rain::Forecast.new(d)}
+    @confidence = data["properties"]["confidence"]
+  end
+
+  def to_locale_timezone(time)
+    time.in_time_zone(position["timezone"])
+  end
+
+  # Estimate the date of the next rain.
+  #
+  # Returns:
+  #    A datetime instance representing the date estimation of the next rain within
+  #    the next hour.
+  #    If no rain is expected in the following hour nil is returned.
+  def next_rain_date(use_position_timezone)
+    # search first cadran with rain
+    next_rain = forecasts.find {|f| f.intensity > 1}
+
+    next_rain&.time
+  end
+end
+
+require "meteofrance_api/models/rain/forecast"

data/lib/meteofrance_api/models/warning/current.rb

@@ -0,0 +1,44 @@
+# Class to access the results of a `warning/currentPhenomenons` REST API request.
+#
+# For coastal department two bulletins are avalaible corresponding to two different
+# domains.
+class MeteofranceApi::Warning::Current
+  # update time of the phenomenoms.
+  attr_reader :update_time
+  # end of validty time of the phenomenoms.
+  attr_reader :end_validity_time
+  # domain ID of the phenomenons. Value is 'France' or a department number
+  attr_reader :domain_id
+  # List of Phenomenon
+  attr_reader :phenomenons
+
+  def initialize(data)
+    @update_time = Time.at(data["update_time"])
+    @end_validity_time = Time.at(data["end_validity_time"])
+    @domain_id = data["domain_id"]
+    @phenomenons = (data["phenomenons_max_colors"] || []).map {|i| Warning::Phenomenon.new(i)}
+  end
+
+  # Merge the classical phenomenoms bulleting with the coastal one.
+
+  # Extend the phenomenomes_max_colors property with the content of the coastal
+  # weather alert bulletin.
+
+  # Args:
+  #     coastal_phenomenoms: WarningCurrentPhenomenons instance corresponding to the
+  #         coastal weather alert bulletin.
+  # 
+  def merge_with_coastal_phenomenons!(coastal_phenomenons)
+    # TODO: Add consitency check
+    @phenomenons += coastal_phenomenoms.phenomenons
+  end
+
+  # Get the maximum level of alert of a given domain (class helper).
+  # Returns:
+  #    An integer corresponding to the status code representing the maximum alert.
+  def get_domain_max_color
+    phenomenons.map {|item| item.max_color_id}.max
+  end
+end
+
+require "meteofrance_api/models/warning/phenomenon"

data/lib/meteofrance_api/models/warning/full.rb

@@ -0,0 +1,67 @@
+# This class allows to access the results of a `warning/full` API command.
+#
+# For a given domain we can access the maximum alert, a timelaps of the alert
+# evolution for the next 24 hours, and a list of alerts.
+#
+# For coastal department two bulletins are avalaible corresponding to two different
+# domains.
+class MeteofranceApi::Warning::Full
+  # update time of the full bulletin.
+  attr_reader :update_time
+  # end of validty time of the full bulletin.
+  attr_reader :end_validity_time
+  # domain ID of the the full bulletin. Value is 'France' or a department number.
+  attr_reader :domain_id
+  # color max of the domain.
+  attr_reader :color_max
+  # timelaps of each phenomenom for the domain. A list of Hash corresponding to the schedule of each phenomenons in the next 24 hours
+  attr_reader :timelaps
+  # phenomenom list of the domain.
+  attr_reader :phenomenons
+
+  attr_reader :advices
+  attr_reader :consequences
+  attr_reader :max_count_items
+  attr_reader :comments
+  attr_reader :text
+  attr_reader :text_avalanche
+
+  def initialize(data)
+    @update_time = Time.at(data["update_time"])
+    @end_validity_time = Time.at(data["end_validity_time"])
+    @domain_id = data["domain_id"]
+    @color_max = data["color_max"]
+    @timelaps = data["timelaps"]
+    @phenomenons = (data["phenomenons_items"] || []).map {|i| MeteofranceApi::Warning::Phenomenon.new(i)}
+
+    @advices = data["advices"]
+    @consequences = data["consequences"]
+    @max_count_items = data["max_count_items"]
+    @comments = data["comments"]
+    @text = data["text"]
+    @text["text_avalanche"]
+  end
+
+  # Merge the classical phenomenon bulletin with the coastal one.
+
+  # Extend the color_max, timelaps and phenomenons properties with the content
+  #     of the coastal weather alert bulletin.
+
+  # Args:
+  #     coastal_phenomenoms: Full instance corresponding to the coastal weather
+  #         alert bulletin.
+  def merge_with_coastal_phenomenons!(coastal_phenomenons)
+    # TODO: Add consitency check
+    # TODO: Check if other data need to be merged
+
+    @color_max = [color_max, coastal_phenomenons.color_max].max
+
+    # Merge timelaps
+    @timelaps += coastal_phenomenons.timelaps
+
+    # Merge phenomenons
+    @phenomenons += coastal_phenomenons.phenomenons
+  end
+end
+
+require "meteofrance_api/models/warning/phenomenon"

data/lib/meteofrance_api/models/warning/phenomenon.rb

@@ -0,0 +1,9 @@
+class MeteofranceApi::Warning::Phenomenon
+  attr_reader :id
+  attr_reader :max_color_id
+
+  def initialize(data)
+    @id = data["phenomenon_id"]
+    @max_color_id = data["phenomenon_max_color_id"]
+  end
+end

data/lib/meteofrance_api/models/warning.rb

@@ -0,0 +1,5 @@
+module MeteofranceApi::Warning
+end
+
+require "meteofrance_api/models/warning/current"
+require "meteofrance_api/models/warning/full.rb"

data/lib/meteofrance_api/models/weather/daily_forecast.rb

@@ -0,0 +1,35 @@
+class MeteofranceApi::Weather::DailyForecast
+  attr_reader :time
+
+  attr_reader :T_max
+  attr_reader :T_min
+  attr_reader :T_sea
+
+  attr_reader :relative_humidity_max
+  attr_reader :relative_humidity_min
+
+  attr_reader :daily_weather_description
+  attr_reader :daily_weather_icon
+
+  attr_reader :sunrise_time
+  attr_reader :sunset_time
+
+  attr_reader :total_precipitation_24h
+
+  attr_reader :uv_index
+
+  def initialize(data)
+    @time = Time.parse(data["time"])
+    @temperature_max = data["T_max"]
+    @temperature_min = data["T_min"]
+    @temperature_sea = data["T_sea"]
+    @relative_humidity_max = data["relative_humidity_max"]
+    @relative_humidity_min = data["relative_humidity_min"]
+    @weather_description = data["daily_weather_description"]
+    @weather_icon = data["daily_weather_icon"]
+    @sunrise_time = Time.parse(data["sunrise_time"])
+    @sunset_time = Time.parse(data["sunset_time"])
+    @total_precipitation_24h = data["total_precipitation_24h"]
+    @uv_index = data["uv_index"]
+  end
+end

data/lib/meteofrance_api/models/weather/forecast.rb

@@ -0,0 +1,63 @@
+class MeteofranceApi::Weather::Forecast
+  attr_reader :time
+
+  attr_reader :temperature
+  attr_reader :temperature_windchill
+  attr_reader :relative_humidity
+
+  attr_reader :total_cloud_cover
+
+  attr_reader :weather_description
+  attr_reader :weather_icon
+
+  attr_reader :wind_direction
+  attr_reader :wind_icon
+  attr_reader :wind_speed
+  attr_reader :wind_speed_gust
+
+  attr_reader :rain_1h
+  attr_reader :rain_3h
+  attr_reader :rain_6h
+  attr_reader :rain_12h
+  attr_reader :rain_24h
+
+  attr_reader :rain_snow_limit
+
+  attr_reader :snow_1h
+  attr_reader :snow_3h
+  attr_reader :snow_6h
+  attr_reader :snow_12h
+  attr_reader :snow_24h
+
+  attr_reader :P_sea
+
+  attr_reader :iso0
+
+
+  def initialize(data)
+    @time = Time.parse(data["time"])
+    @temperature = data["T"]
+    @temperature_windchill = data["T_windchill"]
+    @relative_humidity = data["relative_humidity"]
+    @P_sea = data["P_sea"]
+    @wind_speed = data["wind_speed"]
+    @wind_speed_gust = data["wind_speed_gust"]
+    @wind_direction = data["wind_direction"]
+    @wind_icon = data["wind_icon"]
+    @rain_1h = data["rain_1h"]
+    @rain_3h = data["rain_3h"]
+    @rain_6h = data["rain_6h"]
+    @rain_12h = data["rain_12h"]
+    @rain_24h = data["rain_24h"]
+    @snow_1h = data["snow_1h"]
+    @snow_3h = data["snow_3h"]
+    @snow_6h = data["snow_6h"]
+    @snow_12h = data["snow_12h"]
+    @snow_24h = data["snow_24h"]
+    @iso0 = data["iso0"]
+    @rain_snow_limit = data["rain_snow_limit"]
+    @total_cloud_cover = data["total_cloud_cover"]
+    @weather_icon = data["weather_icon"]
+    @weather_description = data["weather_description"]
+  end
+end

data/lib/meteofrance_api/models/weather/hazard_forecast.rb

@@ -0,0 +1,17 @@
+class MeteofranceApi::Weather::HazardForecast
+  attr_reader :rain_hazard_3h
+  attr_reader :rain_hazard_6h
+  attr_reader :snow_hazard_3h
+  attr_reader :snow_hazard_6h
+  attr_reader :freezing_hazard
+  attr_reader :storm_hazard
+
+  def initialize(data)
+  @rain_hazard_3h = data["rain_hazard_3h"]
+  @rain_hazard_6h = data["rain_hazard_6h"]
+  @snow_hazard_3h = data["snow_hazard_3h"]
+  @snow_hazard_6h = data["snow_hazard_6h"]
+  @freezing_hazard = data["freezing_hazard"]
+  @storm_hazard = data["storm_hazard"]
+  end
+end

data/lib/meteofrance_api/models/weather.rb

@@ -0,0 +1,89 @@
+class MeteofranceApi::Weather
+  # update Time of the forecast.
+  attr_reader :updated_at
+
+  # position information of the forecast. An Array [longitude, latitude].
+  attr_reader :position
+  # Altitude of the position (in meter)
+  attr_reader :altitude
+  # Name of the position
+  attr_reader :name
+  # Country of the position
+  attr_reader :country
+  attr_reader :timezone
+  attr_reader :insee
+  attr_reader :french_department_code
+
+  attr_reader :bulletin_cote
+
+  # daily forecast for the following days.
+  # A list of Hash to describe the daily forecast for the next 15 days.
+  attr_reader :daily_forecasts
+  # hourly forecast.
+  # A list of Hash to describe the hourly forecast for the next day
+  attr_reader :forecasts
+  # wheather event forecast.
+  # A list of object to describe the event probability forecast (rain, snow, freezing) for next 10 days.
+  attr_reader :hazard_forecasts
+
+
+  def initialize(data)
+    @updated_on = Time.at(data["updated_time"])
+
+    @position = data["geometry"]["coordinates"]
+    @altitude = data["properties"]["altitude"]
+    @name = data["properties"]["name"]
+    @country = data["properties"]["country"]
+    @timezone = data["properties"]["timezone"]
+    @insee = data["properties"]["insee"]&.to_i
+    @french_department_code = data["properties"]["french_department_code"]&.to_i
+
+    @bulletin_cote = data["properties"]["bulletin_cote"]
+
+    @daily_forecasts = data.dig("daily_forecast", []).map {|d| MeteofranceApi::Weather::DailyForecast.new(d)}
+    @forecasts = data.dig("forecast", []).map {|d| MeteofranceApi::Weather::Forecast.new(d)}
+    @hazard_forecasts = data.dig("probability_forecast", []).map {|d| MeteofranceApi::Weather::HazardForecast.new(d)}
+  end
+
+  # Return the forecast for today. A Hash corresponding to the daily forecast for the current day
+  def today_forecast
+    self.daily_forecasts.first
+  end
+
+  # Return the nearest hourly forecast. A Hash corresponding to the nearest hourly forecast.
+  def nearest_forecast
+    # get timestamp for current time
+    now_timestamp = Time.now
+
+    # sort list of forecast by distance between current timestamp and
+    # forecast timestamp
+    sorted_forecasts = self.forecasts.sort_by {|f| (f.time - now_timestamp).abs }
+
+    sorted_forecasts.first
+  end
+
+  # Return the forecast of the current hour. A Hash corresponding to the hourly forecast for the current hour
+  def current_forecast
+    # Get the timestamp for the current hour.
+    current_hour = Time.now.utc.to_a
+    current_hour[0] = 0
+    current_hour[1] = 0
+    current_hour_timestamp = Time.utc.new(*current_hour).to_i
+
+    # create a Hash using timestamp as keys
+    forecasts_by_datetime = self.forecasts.map {|f| [f.time.to_i, f]}.to_h
+
+    # Return the forecast corresponding to the timestamp of the current hour if
+    # exists.
+    forecasts_by_datetime[current_hour_timestamp]
+  end
+
+  # Convert time in the forecast location timezone
+  def to_locale_time(time)
+    time.in_time_zone(timezone)
+  end
+end
+
+require "meteofrance_api/models/weather/forecast"
+require "meteofrance_api/models/weather/daily_forecast"
+require "meteofrance_api/models/weather/hazard_forecast"

data/lib/meteofrance_api/models.rb

@@ -0,0 +1,4 @@
+require "meteofrance_api/models/weather"
+require "meteofrance_api/models/place"
+require "meteofrance_api/models/rain"
+require "meteofrance_api/models/warning"

data/lib/meteofrance_api/version.rb

@@ -0,0 +1,3 @@
+module MeteofranceApi
+  VERSION = "0.1.0"
+end

data/lib/meteofrance_api.rb

@@ -0,0 +1,10 @@
+module MeteofranceApi
+  class Error < StandardError; end
+  # Your code goes here...
+end
+
+require "meteofrance_api/client"
+require "meteofrance_api/constants"
+require "meteofrance_api/helpers"
+require "meteofrance_api/models"
+require "meteofrance_api/version"

data/meteofrance-api.gemspec

@@ -0,0 +1,44 @@
+
+lib = File.expand_path("../lib", __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "meteofrance_api/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "meteofrance-api"
+  spec.version       = MeteofranceApi::VERSION
+  spec.authors       = ["Thomas Kuntz"]
+  spec.email         = ["thomaskuntz67@gmail.com"]
+
+  spec.summary       = %q{Wrapper around meteofrance.com (french weather website) API.}
+  spec.description   = %q{Wrapper around meteofrance.com non-public API. Based on Python lib https://github.com/hacf-fr/meteofrance-api}
+  spec.homepage      = "https://github.com/Haerezis/meteofrance-api"
+  spec.license       = "MIT"
+
+  # Prevent pushing this gem to RubyGems.org. To allow pushes either set the 'allowed_push_host'
+  # to allow pushing to a single host or delete this section to allow pushing to any host.
+  if spec.respond_to?(:metadata)
+    #spec.metadata["allowed_push_host"] = "TODO: Set to 'http://mygemserver.com'"
+
+    spec.metadata["homepage_uri"] = spec.homepage
+    spec.metadata["source_code_uri"] = "https://github.com/Haerezis/meteofrance-api"
+    spec.metadata["changelog_uri"] = "https://github.com/Haerezis/meteofrance-api/blob/main/CHANGELOG.md"
+  else
+    raise "RubyGems 2.0 or newer is required to protect against " \
+      "public gem pushes."
+  end
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files         = Dir.chdir(File.expand_path('..', __FILE__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  end
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "faraday", "~> 2.3.0"
+
+  spec.add_development_dependency "bundler", "~> 1.17"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "minitest", "~> 5.0"
+end