Module: LibTAD::Client::TimeService

Included in:
LibTAD::Client
Defined in:
lib/services/time.rb

Overview

Time API.

Instance Method Summary collapse

Instance Method Details

#convert_time(from_id:, to_id: nil, iso: nil, datetime: nil, lang: nil, radius: nil, time_changes: nil, timezone: nil) ⇒ ::LibTAD::TADTime::TADTime, Array<::LibTAD::Places::Locations>

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).

Parameters:

  • from_id (String) —

    Specify the ID of the location for which the supplied time stamp corresponds.

  • to_id (String) (defaults to: nil) —

    Specify the ID or a list of ID’s for the location(s) for which the time stamp should be converted.

  • iso (String) (defaults to: nil) —

    Time stamp in ISO8601 format.

  • datetime (::LibTAD::TADTime::TADDateTime) (defaults to: nil) —

    A date object.

  • lang (String) (defaults to: nil) —

    The preferred language for the texts.

  • radius (Integer) (defaults to: nil) —

    Search radius for translating coordinates to locations.

  • time_changes (Boolean) (defaults to: nil) —

    Add a list of time changes during the year to the location object.

  • timezone (Boolean) (defaults to: nil) —

    Add time zone information under the time object.

Returns:



67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
 
# File 'lib/services/time.rb', line 67

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

#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) ⇒ Array<::LibTAD::Places::Location>

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.

Parameters:

  • place_id (String) (defaults to: nil) —

    Specify the ID or a list of the ID’s for a location which you would like to get the current time from.

  • query (String) (defaults to: nil) —

    Query for a location by specifying the name.

  • qlimit (Integer) (defaults to: nil) —

    Maximum number of query results to be returned.

  • geo (Boolean) (defaults to: nil) —

    Return longitude and latitude for the geo object.

  • lang (String) (defaults to: nil) —

    The preferred language for the texts.

  • radius (Integer) (defaults to: nil) —

    Search radius for translating coordinates to locations.

  • sun (Boolean) (defaults to: nil) —

    Controls if the astronomy element with information about sunrise and sunset shall be added to the result.

  • time (Boolean) (defaults to: nil) —

    Adds current time under the location object.

  • time_changes (Boolean) (defaults to: nil) —

    Adds a list of thime changes during the year to the location object.

  • timezone (Boolean) (defaults to: nil) —

    Adds time zone information under the time object.

Returns:



21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
 
# File 'lib/services/time.rb', line 21

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

#get_daylight_savings_time(year: nil, country: nil, lang: nil, list_places: nil, only_dst: nil, time_changes: nil) ⇒ Array<::LibTAD::DST::DSTEntry>

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.

Parameters:

  • year (Integer) (defaults to: nil) —

    The year you want to retrieve the information for. Defaults to current year.

  • country (String) (defaults to: nil) —

    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.

  • lang (String) (defaults to: nil) —

    The preferred language for the texts.

  • list_places (Boolean) (defaults to: nil) —

    For every time zone/country, list the individual places that belong to each record.

  • only_dst (Boolean) (defaults to: nil) —

    Return only countries which actually observe DST in the queried year. Other countries will be suppressed.

  • time_changes (Boolean) (defaults to: nil) —

    Add a list of time changes during the year to the dstentry object.

Returns:

  • (Array<::LibTAD::DST::DSTEntry>) 


115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
 
# File 'lib/services/time.rb', line 115

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