libtad 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d0199d049a73b8fd060defe6dc08ab230bc3718e4b2ba9f38ade44babcfdf3d8
+  data.tar.gz: 714efc2a4105145b43b440bdb0eea3d21fbf341a269918a29d725df4eaa4a1ee
+SHA512:
+  metadata.gz: 7c95e56ed533e92252e67250f637d48fb7fd938933a71476c0653722e7a3962c125c8ca0b756c0da3de8aa254fafbbf819de7fa18547e48804418f3b7374e6e8
+  data.tar.gz: ab7994a5b52a3fab73f0d00748fbae874b3e8c7d51b0b67bb4a2b6a0b2949700e6672792f71f46fdf525b171a3ca1c46d14040d28a197897d35730a55af494df

data/lib/libtad.rb

@@ -0,0 +1,123 @@
+require 'services/astronomy'
+require 'services/date_calculator'
+require 'services/holidays'
+require 'services/onthisday'
+require 'services/places'
+require 'services/time'
+
+require 'types/astronomy/astronomy_current'
+require 'types/astronomy/astronomy_day'
+require 'types/astronomy/astronomy_day_event'
+require 'types/astronomy/astronomy_event'
+require 'types/astronomy/astronomy_event_class'
+require 'types/astronomy/astronomy_location'
+require 'types/astronomy/astronomy_object'
+require 'types/astronomy/astronomy_object_details'
+require 'types/astronomy/astronomy_object_type'
+require 'types/astronomy/moonphase'
+
+require 'types/date_calculator/business_days_filter'
+require 'types/date_calculator/business_holiday'
+require 'types/date_calculator/period'
+require 'types/date_calculator/weekdays'
+
+require 'types/holidays/holiday'
+require 'types/holidays/holiday_state'
+require 'types/holidays/holiday_type'
+
+require 'types/onthisday/event'
+require 'types/onthisday/event_type'
+require 'types/onthisday/name'
+require 'types/onthisday/person'
+
+require 'types/places/country'
+require 'types/places/geo'
+require 'types/places/location'
+require 'types/places/location_ref'
+require 'types/places/place'
+require 'types/places/region'
+
+require 'types/time/datetime'
+require 'types/time/dst_entry'
+require 'types/time/time'
+require 'types/time/time_change'
+require 'types/time/timezone'
+
+require 'base64'
+require 'json'
+require 'net/http'
+require 'openssl'
+
+module LibTAD
+  # Main endpoint for accessing the Time and Date APIs.
+  class Client
+
+    include LibTAD::Client::AstronomyService
+    include LibTAD::Client::DateCalculatorService
+    include LibTAD::Client::HolidaysService
+    include LibTAD::Client::OnThisDayService
+    include LibTAD::Client::PlacesService
+    include LibTAD::Client::TimeService
+
+    # The endpoint the client connects to.
+    ENDPOINT = 'https://api.xmltime.com/'.freeze
+
+    # Client user agent.
+    USER_AGENT = 'libtad-ruby-0.1.0'.freeze
+
+    # API version.
+    VERSION = 3.freeze
+
+    def initialize(access_key:, secret_key:)
+      @access_key = access_key
+      @secret_key = secret_key
+    end
+
+    private
+
+    def authenticate(service, args)
+      timestamp = ::Time.now.utc.strftime('%FT%T')
+      message = @access_key + service + timestamp
+
+      hmac = OpenSSL::HMAC.digest('sha1', @secret_key, message)
+      signature = Base64.encode64(hmac).chomp
+
+      args[:accesskey] = @access_key
+      args[:signature] = signature
+      args[:timestamp] = timestamp
+
+      args
+    end
+
+    def get(service, args)
+      args = args.transform_values! do |e|
+        if [true, false].include?(e)
+          e && 1 || 0
+        else
+          e
+        end
+      end
+
+      args[:version] = VERSION
+      args = authenticate(service, args)
+
+      uri = URI(ENDPOINT + service)
+      uri.query = URI.encode_www_form(args)
+
+      request = Net::HTTP::Get.new(uri)
+      request["User-Agent"] = USER_AGENT
+
+      res = Net::HTTP.start(uri.hostname, uri.port, :use_ssl => (uri.scheme == 'https')) {|http|
+        http.request(request)
+      }
+
+      res = JSON.parse(res.body)
+
+      if (error = res.fetch('errors', nil))
+        raise Exception.new error
+      else
+        res
+      end
+    end
+  end
+end

data/lib/services/astronomy.rb

@@ -0,0 +1,102 @@
+require 'date'
+
+module LibTAD
+  class Client
+    # Astronomy API.
+    module AstronomyService
+      # @return [Array<::LibTAD::Astronomy::AstronomyLocation>]
+      # @param object [Symbol] Specify an object type to retrieve information about.
+      # @param place_id [String] Specify the ID or a list of IDs of the location(s) you would like to retrieve information for.
+      # @param start_date [String] Specify the ISO 8601 date for the first date you are interested in. Defaults to current date.
+      # @param end_date [String] The last date you are interested in. The service can be used to calculate data for a maximum of 31 days in a row. 
+      #   If the end date is omitted, only one day is retrieved.
+      # @param types [Symbol or Array<Symbol>] Specify an astronomical event class or a list of classes to filter by.
+      # @param geo [Boolean] Return longitude and latitude for the geo object.
+      # @param isotime [Boolean] Adds time stamps (local time) in ISO 8601 format to all events.
+      # @param lang [String] Preferred language for texts.
+      # @param radius [Integer] Search radius for translating coordinates to locations.
+      # @param utctime [Boolean] Adds UTC time stamps in ISO 8601 format to all events.
+      # @see ::LibTAD::Astronomy::ASTRONOMY_OBJECT_TYPE
+      # @see ::LibTAD::Astronomy::ASTRONOMY_EVENT_CLASS
+      #
+      # The Astro Event service can be used retrieve the sunrise, sunset, moonrise, moonset, solar noon and twilight times for all
+      # locations in our database. The service also returns the azimuth of the events, the altitude, and the distance to the sun for the noon event.
+      def get_astro_events(
+        object:,
+        place_id:,
+        start_date: nil,
+        end_date: nil,
+        types: nil,
+        geo: nil,
+        isotime: nil,
+        lang: nil,
+        radius: nil,
+        utctime: nil
+      )
+        args = {
+          object: (object unless !::LibTAD::Astronomy::ASTRONOMY_OBJECT_TYPE.include?(object)),
+          placeid: place_id,
+          startdt: if start_date.nil? then ::Time.now.strftime('%Y-%m-%d') else start_date end,
+          enddt: end_date,
+          types: (types unless ![*types].all? { |e| ::LibTAD::Astronomy::ASTRONOMY_EVENT_CLASS.include?(e) }),
+          geo: geo,
+          isotime: isotime,
+          lang: lang,
+          radius: radius,
+          utctime: utctime
+        }.compact
+
+        response = get('astronomy', args)
+        astroevents = response.fetch('locations', [])
+
+        astroevents.collect do |e|
+          ::LibTAD::Astronomy::AstronomyLocation.new(e)
+        end
+      end
+
+
+      # @return [Array<::LibTAD::Astronomy::AstronomyLocation>]
+      # @param object [Symbol] Specify an object type to retrieve information about.
+      # @param place_id [String] Specify the ID of the location you would like to retrieve information for.
+      # @param interval [String or Array<String>] Specify the point or a list of points in time you would like to calculate data for.
+      # @param localtime [Boolean] Specify whether or not the intervals should be considered the local time for the place(s) or UTC time.
+      # @param utctime [Boolean] Adds UTC time stamps in ISO 8601 format to all events.
+      # @param isotime [Boolean] Adds time stamps (local time) in ISO 8601 format to all events.
+      # @param lang [String] Preferred language for texts.
+      # @param radius [Integer] Search radius for translating coordinates to locations.
+      # @see ::LibTAD::Astronomy::ASTRONOMY_OBJECT_TYPE
+      #
+      # The Astro Position service can be used to retrieve the altitude, azimuth and distance to the Moon and the Sun for all locations in our database.
+      # The service also returns the moon phase, the fraction of the Moon's illuminated side as well as the midpoint angle of the Moon's bright limb at any point in time.
+      # Unlike the Astro Event service, the Astro Position service can be queried on a specific point in time, down to the second.
+      def get_astro_position(
+        object:,
+        place_id:,
+        interval:,
+        localtime: nil,
+        utctime: nil,
+        isotime: nil,
+        lang: nil,
+        radius: nil
+      )
+        args = {
+          object: (object unless !::LibTAD::Astronomy::ASTRONOMY_OBJECT_TYPE.include?(object)),
+          placeid: place_id,
+          interval: interval,
+          localtime: localtime,
+          utctime: utctime,
+          isotime: isotime,
+          lang: lang,
+          radius: radius
+        }.compact
+
+        response = get('astrodata', args)
+        astropositions = response.fetch('locations', [])
+
+        astropositions.collect do |e|
+          ::LibTAD::Astronomy::AstronomyLocation.new(e)
+        end
+      end
+    end
+  end
+end

data/lib/services/date_calculator.rb

@@ -0,0 +1,155 @@
+module LibTAD
+  class Client
+    # Date Calculator API.
+    module DateCalculatorService
+      # @return [::LibTAD::Places::Geo, Array<::LibTAD::DateCalculator::Period>]
+      # @param place_id [String] Specify the ID of the location you would like to calculate the business date.
+      #   The ID is used to find what holidays are applicable for the given place so the calculation can exclude or include those results.
+      # @param country [String] Specify the country for which you would like to calculate the business date.
+      # @param state [String] Specify the state in the given country you want to calculate the business date.
+      # @param start_date [::LibTAD::TADTime::TADDateTime or String] Specify the start date. Takes a TADDateTime object or a ISO 8601 date string.
+      # @param days [Integer] Specify an amount or a list of amounts of business days to count.
+      # @param including [Boolean] Specify whether the result should be calculated by including instead of excluding the days.
+      # @param filter [Symbol] Specify a type or a list of types to filter by.
+      # @param repeat [Integer] Set how many times the calculation should be repeated.
+      # @param lang [String] The preferred language for the texts.
+      # @see ::LibTAD::DateCalculator::BUSINESS_DAYS_FILTER
+      #
+      # The Businessdate service can be used to find a business date from a specified number of days.
+      # By default the result will be filtered on excluding weekends and public holidays, but you can specify a custom filter to modify this.
+      #
+      # Either place_id or country is required.
+      def add_days(
+        place_id: nil,
+        country: nil,
+        state: nil,
+        start_date:,
+        days:,
+        including: nil,
+        filter: nil,
+        repeat: nil,
+        lang: nil
+      )
+        args = {
+          placeid: place_id,
+          country: country,
+          state: state,
+          startdt: if start_date.methods.include?(:to_iso8601) then start_date.to_iso8601 else start_date end,
+          days: days,
+          include: including,
+          filter: (filter unless ![*filter].all? { |e| ::LibTAD::DateCalculator::BUSINESS_DAYS_FILTER.include?(e) }),
+          repeat: repeat,
+          lang: lang
+        }.compact
+
+        call_business_date(args, 'add')
+      end
+
+      # @return [::LibTAD::Places::Geo, Array<::LibTAD::DateCalculator::Period>]
+      # @param place_id [String] Specify the ID of the location you would like to calculate the business date.
+      #   The ID is used to find what holidays are applicable for the given place so the calculation can exclude or include those results.
+      # @param country [String] Specify the country for which you would like to calculate the business date.
+      # @param state [String] Specify the state in the given country you want to calculate the business date.
+      # @param start_date [::LibTAD::TADTime::TADDateTime or String] Specify the start date. Takes a TADDateTime object or a ISO 8601 date string.
+      # @param days [Integer] Specify an amount or a list of amounts of business days to count.
+      # @param including [Boolean] Specify whether the result should be calculated by including instead of excluding the days.
+      # @param filter [Symbol] Specify a type or a list of types to filter by.
+      # @param repeat [Integer] Set how many times the calculation should be repeated.
+      # @param lang [String] The preferred language for the texts.
+      # @see ::LibTAD::DateCalculator::BUSINESS_DAYS_FILTER
+      #
+      # The Businessdate service can be used to find a business date from a specified number of days.
+      # By default the result will be filtered on excluding weekends and public holidays, but you can specify a custom filter to modify this.
+      #
+      # Either place_id or country is required.
+      def subtract_days(
+        place_id: nil,
+        country: nil,
+        state: nil,
+        start_date:,
+        days:,
+        including: nil,
+        filter: nil,
+        repeat: nil,
+        lang: nil
+      )
+        args = {
+          placeid: place_id,
+          country: country,
+          state: state,
+          startdt: if start_date.methods.include?(:to_iso8601) then start_date.to_iso8601 else start_date end,
+          days: days,
+          include: including,
+          filter: (filter unless ![*filter].all? { |e| ::LibTAD::DateCalculator::BUSINESS_DAYS_FILTER.include?(e) }),
+          repeat: repeat,
+          lang: lang
+        }.compact
+
+        call_business_date(args, 'subtract')
+      end
+
+      # @return [::LibTAD::Places::Geo, ::LibTAD::DateCalculator::Period]
+      # @param place_id [String] Specify the ID of the location you would like to calculate the business duration.
+      #   The ID is used to find what holidays are applicable for the given place so the calculation can exclude or include those results.
+      # @param country [String] Specify the country for which you would like to calculate the business date.
+      # @param state [String] Specify the state in the given country you want to calculate the business date.
+      # @param start_date [::LibTAD::TADTime::TADDateTime or String] Specify the start date. Takes a TADDateTime object or a ISO 8601 date string.
+      # @param end_date [::LibTAD::TADTime::TADDateTime or String] Specify the end date. Takes a TADDateTime object or a ISO 8601 date string.
+      # @param including [Boolean] Specify whether the result should be calculated by including instead of excluding the days.
+      # @param filter [Symbol] Specify a type or a list of types to filter by.
+      # @param include_last_date [Boolean] Whether or not the last date should be counted in the result.
+      # @param lang [String] The preferred language for the texts.
+      # @see ::LibTAD::DateCalculator::BUSINESS_DAYS_FILTER
+      #
+      # The Businessduration service can be used to calculate the number of business days between a specified start date and end date.
+      #
+      # When you query the Businessduration service with a placeid or a country, a start date and an end date the service will return the number
+      # of business days in that date range by excluding public holidays and weekends. Furthermore, you can apply additional filters
+      # such as individual days and whether or not the calculation should include the filter result or exclude it.
+      #
+      # Either place_id or country is required.
+      def get_duration(
+        place_id: nil,
+        country: nil,
+        state: nil,
+        start_date:,
+        end_date:,
+        including: nil,
+        filter: nil,
+        include_last_date: nil,
+        lang: nil
+      )
+        args = {
+          placeid: place_id,
+          country: country,
+          state: state,
+          startdt: if start_date.methods.include?(:to_iso8601) then start_date.to_iso8601 else start_date end,
+          enddt: if end_date.methods.include?(:to_iso8601) then end_date.to_iso8601 else end_date end,
+          include: including,
+          filter: (filter unless ![*filter].all? { |e| ::LibTAD::DateCalculator::BUSINESS_DAYS_FILTER.include?(e) }),
+          includelastdate: include_last_date,
+          lang: lang
+        }.compact
+
+        response = get('businessduration', args)
+        geo = ::LibTAD::Places::Geo.new response['geo'] unless !response.key?('geo')
+        period = ::LibTAD::DateCalculator::Period.new response['period'] unless !response.key?('period')
+
+        return geo, period
+      end
+
+      private
+
+      def call_business_date(args, operation)
+        args[:op] = operation
+
+        response = get('businessdate', args)
+        geo = ::LibTAD::Places::Geo.new response['geo'] unless !response.key?('geo')
+        period = response.fetch('periods', [])
+          .map { |e| ::LibTAD::DateCalculator::Period.new(e) }
+
+        return geo, period
+      end
+    end
+  end
+end

data/lib/services/holidays.rb

@@ -0,0 +1,34 @@
+require 'date'
+
+module LibTAD
+  class Client
+    # Holidays API.
+    module HolidaysService
+      # @return [Array<::LibTAD::Holidays::Holiday>]
+      # @param country [String] Specify the ISO3166-1-alpha-2 Country Code for which you would like to retrieve the list of holidays.
+      # @param year [Integer] The year for which the holidays should be retrieved. Defaults to current year.
+      # @param lang [String or Array<String>] Specify the ISO639 Language Code or a list of codes for the texts.
+      # @param types [Symbol or Array<Symbol>] Specify a holiday type or a list of holiday types to filter by.
+      # @param timezone [Boolean] Adds time zone information under the time object.
+      # @see ::LibTAD::Holidays::HOLIDAY_TYPE
+      #
+      # The Holidays service can be used to retrieve the list of holidays for a country.
+      def get_holidays(country:, year: nil, lang: nil, types: nil, timezone: nil)
+        args = {
+          country: country,
+          lang: lang,
+          types: (types unless ![*types].all? { |e| ::LibTAD::Holidays::HOLIDAY_TYPE.include?(e) }),
+          year: if year.nil? then ::Time.now.year else year end,
+          tz: timezone
+        }.compact
+
+        response = get('holidays', args)
+        holidays = response.fetch('holidays', [])
+
+        holidays.collect do |e|
+          ::LibTAD::Holidays::Holiday.new(e)
+        end
+      end
+    end
+  end
+end

data/lib/services/onthisday.rb

@@ -0,0 +1,42 @@
+module LibTAD
+  class Client
+    # On This Day API.
+    module OnThisDayService
+      # @return [Array<::LibTAD::OnThisDay::Event>, Array<::LibTAD::OnThisDay::Person>, Array<::LibTAD::OnThisDay::Person>]
+      # @param month [Integer] The month for which the events should be retrieved. Defaults to current month.
+      # @param day [Integer] The day for which the events should be retrieved. Defaults to current day.
+      # @param lang [String or Array<String>] Specify the ISO639 Language Code or a list of codes for the texts.
+      # @param types [Symbol or Array<Symbol>] Specify an event type or a list of event types to filter by.
+      # @see ::LibTAD::OnThisDay::EVENT_TYPE
+      #
+      # The On This Day service can be used to retrieve events, births and deaths for a specific date.
+      def get_events_on_this_day(month: nil, day: nil, lang: nil, types: nil)
+        args = {
+          month: month,
+          day: day,
+          lang: lang,
+          types: (types unless ![*types].all? { |e| ::LibTAD::OnThisDay::EVENT_TYPE.include?(e) }),
+        }.compact
+
+        response = get('onthisday', args)
+        events = response.fetch('events', [])
+        births = response.fetch('births', [])
+        deaths = response.fetch('deaths', [])
+
+        events = events.collect do |e|
+          ::LibTAD::OnThisDay::Event.new(e)
+        end
+
+        births = births.collect do |e|
+          ::LibTAD::OnThisDay::Person.new(e)
+        end
+
+        deaths = deaths.collect do |e|
+          ::LibTAD::OnThisDay::Person.new(e)
+        end
+
+        return events, births, deaths
+      end
+    end
+  end
+end