libtad 0.1.0

data/lib/services/places.rb

@@ -0,0 +1,26 @@
+module LibTAD
+  class Client
+    # Places API.
+    module PlacesService
+      # @return [Array<::LibTAD::Places::Place>]
+      # @param geo [Boolean] Return longitude or latitude for the geo object.
+      # @param lang [Boolean] The preferred language for the texts.
+      #
+      # The Places service can be used to retrieve the list of supported places. The ids for the places are 
+      # then used in the other services to indicate the location to be queried.
+      def get_places(geo: nil, lang: nil)
+        args = {
+          geo: geo,
+          lang: lang
+        }.compact
+
+        response = get('places', args)
+        places = response.fetch('places', [])
+
+        places.collect do |e|
+          ::LibTAD::Places::Place.new(e)
+        end
+      end
+    end
+  end
+end

data/lib/services/time.rb

@@ -0,0 +1,143 @@
+module LibTAD
+  class Client
+    # Time API.
+    module TimeService
+      # @return [Array<::LibTAD::Places::Location>]
+      # @param place_id [String] Specify the ID or a list of the ID's for a location which you would like to get the current time from.
+      # @param query [String] Query for a location by specifying the name.
+      # @param qlimit [Integer] Maximum number of query results to be returned.
+      # @param geo [Boolean] Return longitude and latitude for the geo object.
+      # @param lang [String] The preferred language for the texts.
+      # @param radius [Integer] Search radius for translating coordinates to locations.
+      # @param sun [Boolean] Controls if the astronomy element with information about sunrise and sunset shall be added to the result.
+      # @param time [Boolean] Adds current time under the location object.
+      # @param time_changes [Boolean] Adds a list of thime changes during the year to the location object.
+      # @param timezone [Boolean] Adds time zone information under the time object.
+      #
+      # The Time service can be used to retrieve the current time in one or more places.
+      # Additionally, information about time zones and related changes and the time of sunrise and sunset can be queried.
+      #
+      # Either a place_id or a query is required.
+      def get_current_time(
+        place_id: nil,
+        query: nil,
+        qlimit: nil,
+        geo: nil,
+        lang: nil,
+        radius: nil,
+        sun: nil,
+        time: nil,
+        time_changes: nil,
+        timezone: nil
+      )
+        args = {
+          placeid: place_id,
+          query: query,
+          qlimit: qlimit,
+          geo: geo,
+          lang: lang,
+          radius: radius,
+          sun: sun,
+          time: time,
+          timechanges: time_changes,
+          tz: timezone
+        }.compact
+
+        response = get('timeservice', args)
+        locations = response.fetch('locations', [])
+
+        locations.collect do |e|
+          ::LibTAD::Places::Location.new(e)
+        end
+      end
+
+      # @return [::LibTAD::TADTime::TADTime, Array<::LibTAD::Places::Locations>]
+      # @param from_id [String] Specify the ID of the location for which the supplied time stamp corresponds.
+      # @param to_id [String] Specify the ID or a list of ID's for the location(s) for which the time stamp should be converted.
+      # @param iso [String] Time stamp in ISO8601 format.
+      # @param datetime [::LibTAD::TADTime::TADDateTime] A date object.
+      # @param lang [String] The preferred language for the texts.
+      # @param radius [Integer] Search radius for translating coordinates to locations.
+      # @param time_changes [Boolean] Add a list of time changes during the year to the location object.
+      # @param timezone [Boolean] Add time zone information under the time object.
+      #
+      # The Converttime service can be used to convert any time from UTC or any of the supported locations to any other of the supported locations.
+      # You have to specify a time stamp either in ISO8601 representation via the iso argument, or you have to specify the date via the datetime argument.
+      # Skipped components will not yield an error message, but use a default value instead (which corresponds to 01.01.2001, 00:00:00).
+      def convert_time(
+        from_id:,
+        to_id: nil,
+        iso: nil,
+        datetime: nil,
+        lang: nil,
+        radius: nil,
+        time_changes: nil,
+        timezone: nil
+      )
+        args = {
+          fromid: from_id,
+          toid: to_id,
+          iso: iso,
+          year: (datetime.year unless datetime.nil?),
+          month: (datetime.month unless datetime.nil?),
+          day: (datetime.day unless datetime.nil?),
+          hour: (datetime.hour unless datetime.nil?),
+          min: (datetime.minute unless datetime.nil?),
+          sec: (datetime.second unless datetime.nil?),
+          lang: lang,
+          radius: radius,
+          timechanges: time_changes,
+          tz: timezone
+        }.compact
+
+        response = get('converttime', args)
+        utc = ::LibTAD::TADTime::TADTime.new response.dig('utc', 'time') unless response.dig('utc', 'time').nil?
+        locations = response.fetch('locations', [])
+          .map { |e| ::LibTAD::Places::Location.new(e) }
+
+        return utc, locations
+      end
+
+      # @return [Array<::LibTAD::DST::DSTEntry>]
+      # @param year [Integer] The year you want to retrieve the information for. Defaults to current year.
+      # @param country [String] Specify the country for which you want to retrieve information for. If unspecified, information for all countries will be returned.
+      #   Specifying this parameter automatically sets the parameter onlydst to 0.
+      # @param lang [String] The preferred language for the texts.
+      # @param list_places [Boolean] For every time zone/country, list the individual places that belong to each record.
+      # @param only_dst [Boolean] Return only countries which actually observe DST in the queried year. Other countries will be suppressed.
+      # @param time_changes [Boolean] Add a list of time changes during the year to the dstentry object.
+      #
+      # The Dstlist service can be used to obtain data about time zones for all supported countries in our database.
+      # This includes the start and end date of daylight savings time, and UTC offset for the time zones.
+      #
+      # The resulting data is aggregated on country and time zone level. By default, only information from countries which actually observe DST is
+      # returned without listing the individually affected locations – see the parameters list_places and only_dst to change this behavior.
+      def get_daylight_savings_time(
+        year: nil,
+        country: nil,
+        lang: nil,
+        list_places: nil,
+        only_dst: nil,
+        time_changes: nil
+      )
+        args = {
+          year: year,
+          country: country,
+          lang: lang,
+          listplaces: list_places,
+          onlydst: only_dst,
+          timechanges: time_changes
+        }.compact
+
+        response = get('dstlist', args)
+
+        dstlist = response.fetch('dstlist', [])
+
+        dstlist.collect do |e|
+          ::LibTAD::TADTime::DSTEntry.new(e)
+        end
+      end
+    end
+  end
+end
+

data/lib/types/astronomy/astronomy_current.rb

@@ -0,0 +1,58 @@
+module LibTAD
+  module Astronomy
+    # Current information about an astronomy object.
+    class AstronomyCurrent
+      # @return [String]
+      # Local time stamp for the data in ISO 8601 format (including UTC offset).
+      # Only returned if requested by specifying the parameter isotime.
+      #
+      # Example: 2012-04-17T00:57:42+02:00
+      attr_reader :isotime
+
+      # @return [String]
+      # UTC time stamp for the data in ISO 8601 format.
+      # Only returned if requested by specifying the parameter utctime.
+      #
+      # Example: 2012-04-16T22:57:42
+      attr_reader :utctime
+
+      # @return [Float]
+      # Altitude of the center of the queried astronomical object above an ideal horizon.
+      attr_reader :altitude
+
+      # @return [Float] (degrees)
+      # Horizontal direction of the astronomical object at set/rise time (referring to true north).
+      # North is 0 degrees, east is 90 degrees, south is 180 degrees and west is 270 degrees.
+      attr_reader :azimuth
+
+      # @return [Float] (km)
+      # Distance of the earth's center to the center of the queried astronomical object in kilometers.
+      attr_reader :distance
+
+      # @return [Float] (percent)
+      # The fraction of the Moon's surface illuminated by the Sun's rays as seen from the selected location.
+      # Only available for the moon object.
+      attr_reader :illuminated
+
+      # @return [Float] (degrees)
+      # The counterclockwise angle of the midpoint of the Moon's bright limb as seen from the selected location.
+      # Only available for the moon object.
+      attr_reader :posangle
+
+      # @return [MoonPhase]
+      # The current phase of the moon. Only available for the moon object.
+      attr_reader :moonphase
+
+      def initialize(hash)
+        @isotime = hash.fetch('isotime', nil)
+        @utctime = hash.fetch('utctime', nil)
+        @altitude = hash.fetch('altitude', nil)
+        @azimuth = hash.fetch('azimuth', nil)
+        @distance = hash.fetch('distance', nil)
+        @illuminated = hash.fetch('illuminated', nil)
+        @posangle = hash.fetch('posangle', nil)
+        @moonphase = MoonPhase.new hash['moonphase'] unless !hash.key?('moonphase')
+      end
+    end
+  end
+end

data/lib/types/astronomy/astronomy_day.rb

@@ -0,0 +1,32 @@
+module LibTAD
+  module Astronomy
+    # Information about an astronomy object for a specific day.
+    class AstronomyDay
+      # @return [String]
+      # Date for the current information.
+      attr_reader :date
+
+      # @return [String]
+      # Length of this day (time between sunrise and sunset). If the sun is not up on this day, 00:00:00 will reported.
+      # If the sun does not set on this day, the value will read 24:00:00.
+      # Attribute only applies for the sun object and if requested.
+      attr_reader :daylength
+
+      # @return [String]
+      # Moon phase for the day. Only if requested.
+      attr_reader :moonphase
+
+      # @return [Array<AstronomyDayEvent>]
+      # Lists all events during the day.
+      attr_reader :events
+
+      def initialize(hash)
+        @date = hash.fetch('date', nil)
+        @daylength = hash.fetch('daylength', nil)
+        @moonphase = hash.fetch('moonphase', nil)
+        @events = hash.fetch('events', nil)
+          &.map { |e| AstronomyDayEvent.new(e) }
+      end
+    end
+  end
+end

data/lib/types/astronomy/astronomy_day_event.rb

@@ -0,0 +1,76 @@
+module LibTAD
+  module Astronomy
+    # Information about an astronomical event at a specific day.
+    class AstronomyDayEvent
+      # @return [String]
+      # Indicates the type of the event.
+      attr_reader :type
+
+      # @return [Integer]
+      # Hour at which the event is happening (local time).
+      attr_reader :hour
+
+      # @return [Integer]
+      # Minute at which the event is happening (local time).
+      attr_reader :minute
+
+      # @return [Integer]
+      # Second at which the event is happening (local time).
+      attr_reader :second
+
+      # @return [String]
+      # Local time at which the event is happening in ISO 8601 format (including UTC offset).
+      # Only returned if requested by specifying the parameter isotime.
+      #
+      # Example: 2012-04-17T00:57:42+02:00
+      attr_reader :isotime
+
+      # @return [String]
+      # UTC time at which the event is happening in ISO 8601 format.
+      # Only returned if requested by specifying the parameter utctime.
+      #
+      # Example: 2012-04-16T22:57:42
+      attr_reader :utctime
+
+      # @return [Float] (degrees)
+      # Altitude of the center of the queried astronomical object above an ideal horizon.
+      # Only for meridian type events.
+      attr_reader :altitude
+
+      # @return [Float] (degrees)
+      # Horizontal direction of the astronomical object at set/rise time (referring to true north).
+      # North is 0 degrees, east is 90 degrees, south is 180 degrees and west is 270 degrees.
+      # Only for rise and set type events.
+      attr_reader :azimuth
+
+      # @return [Float] (km)
+      # Distance of the earth's center to the center of the queried astronomical object in kilometers.
+      # Only for meridian type events.
+      attr_reader :distance
+
+      # @return [Float] (percent)
+      # The fraction of the Moon's surface illuminated by the Sun's rays as seen from the selected location.
+      # Only for the moon for meridian type events.
+      attr_reader :illuminated
+
+      # @return [Float] (degrees)
+      # The counterclockwise angle of the midpoint of the Moon's bright limb as seen from the selected location.
+      # Only for the moon for meridian type events.
+      attr_reader :posangle
+
+      def initialize(hash)
+        @type = hash.fetch('type', nil)
+        @hour = hash.fetch('hour', nil)
+        @min = hash.fetch('min', nil)
+        @sec = hash.fetch('sec', nil)
+        @isotime = hash.fetch('isotime', nil)
+        @utctime = hash.fetch('utctime', nil)
+        @altitude = hash.fetch('altitude', nil)
+        @azimuth = hash.fetch('azimuth', nil)
+        @distance = hash.fetch('distance', nil)
+        @illuminated = hash.fetch('illuminated', nil)
+        @posangle = hash.fetch('posangle', nil)
+      end
+    end
+  end
+end

data/lib/types/astronomy/astronomy_event.rb

@@ -0,0 +1,24 @@
+module LibTAD
+  module Astronomy
+    # Information about a sunrise/sunset event for a specific day.
+    class AstronomyEvent
+      # @return [String]
+      # Indicates the type of the event.
+      attr_reader :type
+
+      # @return [Integer]
+      # Hour at which the event is happening (local time).
+      attr_reader :hour
+
+      # @return [Integer]
+      # Minute at which the event is happening (local time).
+      attr_reader :minute
+
+      def initialize(hash)
+        @type = hash.fetch('type', nil)
+        @hour = hash.fetch('hour', nil)
+        @minute = hash.fetch('minute', nil)
+      end
+    end
+  end
+end

data/lib/types/astronomy/astronomy_event_class.rb

@@ -0,0 +1,37 @@
+module LibTAD
+  module Astronomy
+    # All valid astronomy event classes
+    ASTRONOMY_EVENT_CLASS = [
+      # Combination of all known classes.
+      :all,
+
+      # The current phase for the place requested. Additional attributes for illumination (moon), azimuth, distance. 
+      :current,
+
+      # Day length. Day length is not reported as an event, but as a separate attribute.
+      :daylength,
+
+      # Meridian (Noon, highest point) and Anti-Meridian (lowest point) events.
+      :meridian,
+
+      # Moon phase events. Additionally to the phase events (only occurring on four days per lunar month),
+      # an additional attribute for the current moon phase is reported for every day.
+      :phase,
+  
+      # Set and rise events. Event times take atmospheric refraction into account.
+      :setrise,
+
+      # Combination of all 3 twilight classes.
+      :twilight,
+
+      # Civil twilight (-6°).
+      :twilight6,
+
+      # Nautical twilight (-12°).
+      :twilight12,
+
+      # Astronomical twilight (-18°).
+      :twilight18
+    ].freeze
+  end
+end

data/lib/types/astronomy/astronomy_location.rb

@@ -0,0 +1,31 @@
+module LibTAD
+  module Astronomy
+    # Information about location and astronomical objects requested.
+    class AstronomyLocation
+      # @return [String]
+      # The id of the location.
+      attr_reader :id
+
+      # @return [String]
+      # The part of the queried placeid that this location matches.
+      attr_reader :matchparam
+
+      # @return [GeoType]
+      # Geographical information about the location.
+      attr_reader :geo
+
+      # @return [Array<AstronomyObjectDetails>]
+      # Requested astronomical information.
+      attr_reader :objects
+
+      def initialize(hash)
+        @id = hash.fetch('id', nil)
+        @matchparam = hash.fetch('matchparam', nil)
+        @geo = ::LibTAD::Places::Geo.new hash.fetch('geo', nil)
+        @objects = hash.fetch('astronomy', nil)
+          &.fetch('objects', nil)
+          &.map { |e| AstronomyObjectDetails.new(e) }
+      end
+    end
+  end
+end

data/lib/types/astronomy/astronomy_object.rb

@@ -0,0 +1,27 @@
+module LibTAD
+  module Astronomy
+    # Astronomical information - sunrise and sunset times.
+    class AstronomyObject
+      # @return [String]
+      # Object name. Currently, the sun is the only supported astronomical object.
+      attr_reader :name
+
+      # @return [Array<AstronomyEvent>]
+      # Lists all sunrise/sunset events during the day.
+      attr_reader :events
+
+      # @return [String]
+      # This element is only present if there are no astronomical events.
+      # In this case it will indicate if the sun is up or down the whole day.
+      attr_reader :special
+
+      def initialize(hash)
+        @name = hash.fetch('name', nil)
+        @events = hash.fetch('events', nil)
+          &.map { |e| AstronomyEvent.new(e) }
+
+        @special = hash.dig('special', 'type')
+      end
+    end
+  end
+end