tlaw 0.0.1

data/examples/demo_base.rb

@@ -0,0 +1,10 @@
+require 'pp'
+
+$:.unshift 'lib'
+require 'tlaw'
+
+begin
+  require 'dotenv'
+  Dotenv.load
+rescue LoadError
+end

data/examples/forecast_io.rb

@@ -0,0 +1,113 @@
+module TLAW
+  module Examples
+    class ForecastIO < TLAW::API
+      define do
+        base 'https://api.forecast.io/forecast/{api_key}'
+
+        desc %Q{
+          The Forecast API allows you to look up the weather anywhere on
+          the globe, returning (where available):
+
+          * Current conditions
+          * Minute-by-minute forecasts out to 1 hour
+          * Hour-by-hour forecasts out to 48 hours
+          * Day-by-day forecasts out to 7 days
+        }
+
+        docs 'https://developer.forecast.io/docs/v2'
+
+        param :api_key, required: true,
+          desc: 'Register at https://developer.forecast.io/register to obtain it'
+        param :units, enum: %i[us si ca uk2 auto], default: :us,
+          desc: %Q{
+            Response units. Values:
+            * `:us` is default;
+            * `:si` is meters/celsius/hectopascals;
+            * `:ca` is identical to si, except that `windSpeed` is in
+              kilometers per hour.
+            * `:uk2` is identical to si, except that `windSpeed` is in
+              miles per hour, and `nearestStormDistance` and `visibility`
+              are in miles, as in the US.
+            * `auto` selects the relevant units automatically, based
+              on geographic location.
+          }
+
+        param :lang, default: :en,
+          desc: %Q{
+            Return summary properties in the desired language. (2-letters code)
+          }
+
+        endpoint :forecast, '/{lat},{lng}' do
+          desc %Q{Forecast for the next week.}
+
+          docs 'https://developer.forecast.io/docs/v2#forecast_call'
+
+          param :lat, :to_f, required: true, desc: 'Latitude'
+          param :lng, :to_f, required: true, desc: 'Longitude'
+
+          param :exclude, Array,
+            desc: %Q{
+              Exclude some number of data blocks from the API response.
+              This is useful for reducing latency and saving cache space.
+              Should be a list (without spaces) of any of the following:
+              currently, minutely, hourly, daily, alerts, flags.
+            }
+
+          param :extended_hourly, field: :extend,
+            enum: {false => nil, true => 'hourly'},
+            desc: %Q{
+              When present, return hourly data for the next seven days,
+              rather than the next two.
+            }
+        end
+
+        endpoint :time_machine, '/{lat},{lng},{at}' do
+          desc %Q{
+            Observed weather at a given time (for many places, up to 60
+            years in the past).
+
+            For future dates, returns numerical forecast for the next week
+            and seasonal averages beyond that.
+          }
+
+          docs 'https://developer.forecast.io/docs/v2#time_call'
+
+          param :lat, :to_f, required: true, desc: 'Latitude'
+          param :lng, :to_f, required: true, desc: 'Longitude'
+          param :at, :to_time, format: :to_i, required: true,
+            desc: 'Date in past or future.'
+
+          param :exclude, Array,
+            desc: %Q{
+              Exclude some number of data blocks from the API response.
+              This is useful for reducing latency and saving cache space.
+              Should be a list (without spaces) of any of the following:
+              currently, minutely, hourly, daily, alerts, flags.
+            }
+        end
+
+        post_process 'currently.time', &Time.method(:at)
+
+        post_process_items('minutely.data') {
+          post_process 'time', &Time.method(:at)
+        }
+
+        post_process_items('hourly.data') {
+          post_process 'time', &Time.method(:at)
+        }
+
+        post_process_items('daily.data') {
+          post_process 'time', &Time.method(:at)
+          post_process 'sunriseTime', &Time.method(:at)
+          post_process 'sunsetTime', &Time.method(:at)
+        }
+      end
+    end
+
+    # TODO: X-Forecast-API-Calls header is useful!
+    # TODO: The Forecast Data API supports HTTP compression.
+    #   We heartily recommend using it, as it will make responses much
+    #   smaller over the wire. To enable it, simply add an
+    #   Accept-Encoding: gzip header to your request.
+  end
+end

data/examples/forecast_io_demo.rb

@@ -0,0 +1,72 @@
+#!/usr/bin/env ruby
+require_relative 'demo_base'
+require_relative 'forecast_io'
+
+# This wrapper demo demonstrates that even a simple (one call, several
+# params) API could benefit from TLAW by param types checking &
+# sky-level discoverability.
+
+p TLAW::Examples::ForecastIO
+# #<TLAW::Examples::ForecastIO: call-sequence: TLAW::Examples::ForecastIO.new(api_key:, units: :us, lang: :en); endpoints: forecast, time_machine; docs: .describe>
+
+p TLAW::Examples::ForecastIO.describe
+# TLAW::Examples::ForecastIO.new(api_key:, units: :us, lang: :en)
+#   The Forecast API allows you to look up the weather anywhere on
+#   the globe, returning (where available):
+#
+#   * Current conditions
+#   * Minute-by-minute forecasts out to 1 hour
+#   * Hour-by-hour forecasts out to 48 hours
+#   * Day-by-day forecasts out to 7 days
+#
+#   Docs: https://developer.forecast.io/docs/v2
+#
+#   @param api_key Register at https://developer.forecast.io/register to obtain it
+#   @param units
+#     Response units. Values:
+#     * `:us` is default;
+#     * `:si` is meters/celsius/hectopascals;
+#     * `:ca` is identical to si, except that `windSpeed` is in
+#     kilometers per hour.
+#     * `:uk2` is identical to si, except that `windSpeed` is in
+#     miles per hour, and `nearestStormDistance` and `visibility`
+#     are in miles, as in the US.
+#     * `auto` selects the relevant units automatically, based
+#     on geographic location.
+#
+#     Possible values: :us, :si, :ca, :uk2, :auto (default = :us)
+#   @param lang
+#     Return summary properties in the desired language. (2-letters code)
+#      (default = :en)
+#
+#   Endpoints:
+#
+#   .forecast(lat, lng, exclude: nil, extended_hourly: nil)
+#     Forecast for the next week.
+#
+#   .time_machine(lat, lng, at, exclude: nil)
+#     Observed weather at a given time (for many places, up to 60
+#     years in the past).
+
+# You need to create key here: https://developer.forecast.io/register
+# And run the script this way:
+#
+#    FORECAST_IO={your_id} examples/forecast_io_demo.rb
+#
+
+weather = TLAW::Examples::ForecastIO
+  .new(api_key: ENV['FORECAST_IO'], units: :si)
+
+res = weather.forecast(40.7127, -74.0059, extended_hourly: true)
+pp res['minutely.data'].first
+# {"time"=>2016-09-12 21:20:00 +0300,
+#  "precipIntensity"=>0,
+#  "precipProbability"=>0}
+
+res = weather.time_machine(49.999892, 36.242392, Date.parse('2020-02-01'))
+pp res['daily.data'].columns('time', 'temperatureMin', 'temperatureMax', 'dewPoint', 'moonPhase').first
+# {"time"=>2020-02-01 00:00:00 +0200,
+#  "temperatureMin"=>-6.61,
+#  "temperatureMax"=>-4.37,
+#  "dewPoint"=>-7.7,
+#  "moonPhase"=>0.23}

data/examples/open_weather_map.rb

@@ -0,0 +1,266 @@
+require 'geo/coord'
+
+module TLAW
+  module Examples
+    class OpenWeatherMap < TLAW::API
+      define do
+        desc %Q{
+          API for [OpenWeatherMap](http://openweathermap.org/). Only parts
+          available for free are implemented (as only them could be tested).
+        }
+
+        docs 'http://openweathermap.org/api'
+
+        base 'http://api.openweathermap.org/data/2.5'
+
+        param :appid, required: true,
+          desc: 'You need to receive it at http://openweathermap.org/appid (free)'
+
+        param :lang, default: 'en',
+          desc: %Q{Language of API responses (affects weather description only).
+                   See http://openweathermap.org/current#multi for list of supported languages.}
+
+        param :units, enum: %i[standard metric imperial], default: :standard,
+          desc: 'Units for temperature and other values. Standard is Kelvin.'
+
+        namespace :current, '/weather' do
+          desc %Q{
+            Allows to obtain current weather at one place, designated
+            by city, location or zip code.
+          }
+
+          docs 'http://openweathermap.org/current'
+
+          endpoint :city, '?q={city}{,country_code}' do
+            desc %Q{
+              Current weather by city name (with optional country code
+              specification).
+            }
+
+            docs 'http://openweathermap.org/current#name'
+
+            param :city, required: true, desc: 'City name'
+            param :country_code, desc: 'ISO 3166 2-letter country code'
+          end
+
+          endpoint :city_id, '?id={city_id}' do
+            desc %Q{
+              Current weather by city id. Recommended by OpenWeatherMap
+              docs.
+
+              List of city ID city.list.json.gz can be downloaded at
+              http://bulk.openweathermap.org/sample/
+            }
+
+            docs 'http://openweathermap.org/current#cityid'
+
+            param :city_id, required: true, desc: 'City ID (as defined by OpenWeatherMap)'
+          end
+
+          endpoint :location, '?lat={lat}&lon={lng}' do
+            desc %Q{
+              Current weather by geographic coordinates.
+            }
+
+            docs 'http://openweathermap.org/current#geo'
+
+            param :lat, :to_f, required: true, desc: 'Latitude'
+            param :lng, :to_f, required: true, desc: 'Longitude'
+          end
+
+          endpoint :zip, '?zip={zip}{,country_code}' do
+            desc %Q{
+              Current weather by ZIP code (with optional country code
+              specification).
+            }
+
+            docs 'http://openweathermap.org/current#zip'
+
+            param :zip, required: true, desc: 'ZIP code'
+            param :country_code, desc: 'ISO 3166 2-letter country code'
+          end
+
+          endpoint :group, '/../group?id={city_ids}' do
+            desc %Q{
+              Current weather in several cities by their ids.
+
+              List of city ID city.list.json.gz can be downloaded at
+              http://bulk.openweathermap.org/sample/
+            }
+
+            docs 'http://openweathermap.org/current#cities'
+
+            param :city_ids, :to_a, required: true
+          end
+        end
+
+        namespace :find do
+          desc %Q{
+            Allows to find some place (and weather in it) by set of input
+            parameters.
+          }
+
+          docs 'http://openweathermap.org/current#accuracy'
+
+          endpoint :by_name, '?q={start_with}{,country_code}' do
+            desc %Q{
+              Looks for cities by beginning of their names.
+            }
+
+            docs 'http://openweathermap.org/current#accuracy'
+
+            param :start_with, required: true, desc: 'Beginning of city name'
+            param :country_code, desc: 'ISO 3166 2-letter country code'
+
+            param :cnt, :to_i, range: 1..50, default: 10,
+              desc: 'Max number of results to return'
+
+            param :accurate, field: :type,
+              enum: {true => 'accurate', false => 'like'},
+              default: true,
+              desc: %Q{Accuracy level of result.
+               true returns exact match values (accurate).
+               false returns results by searching for that substring (like).
+              }
+          end
+
+          endpoint :around, '?lat={lat}&lon={lng}' do
+            desc %Q{
+              Looks for cities around geographical coordinates.
+            }
+
+            docs 'http://openweathermap.org/current#cycle'
+
+            param :lat, :to_f, required: true, desc: 'Latitude'
+            param :lng, :to_f, required: true, desc: 'Longitude'
+
+            param :cnt, :to_i, range: 1..50, default: 10,
+              desc: 'Max number of results to return'
+
+            param :cluster, enum: {true => 'yes', false: 'no'},
+              default: true,
+              desc: 'Use server clustering of points'
+          end
+
+          # Real path is api/bbox/city - not inside /find, but logically
+          # we want to place it here
+          endpoint :inside, '/../box/city?bbox={lng_left},{lat_bottom},{lng_right},{lat_top},{zoom}' do
+            desc %Q{
+              Looks for cities inside specified rectangle zone.
+            }
+
+            docs 'http://openweathermap.org/current#rectangle'
+
+            param :lat_top, :to_f, required: true, keyword: true
+            param :lat_bottom, :to_f, required: true, keyword: true
+            param :lng_left, :to_f, required: true, keyword: true
+            param :lng_right, :to_f, required: true, keyword: true
+            param :zoom, :to_i, default: 10, keyword: true,
+              desc: 'Map zoom level.'
+
+            param :cluster, enum: {true => 'yes', false: 'no'},
+              default: true,
+              desc: 'Use server clustering of points'
+          end
+        end
+
+        # http://openweathermap.org/forecast5
+        namespace :forecast do
+          desc %Q{
+            Allows to obtain weather forecast for 5 days with 3-hour
+            frequency.
+
+            NB: OpenWeatherMap also implement [16-day forecast](http://openweathermap.org/forecast16),
+            but it have no free option and can not be tested. That's why
+            we don't implement it.
+          }
+
+          docs 'http://openweathermap.org/forecast5'
+
+          endpoint :city, '?q={city}{,country_code}' do
+            desc %Q{
+              Weather forecast by city name (with optional country code
+              specification).
+            }
+
+            docs 'http://openweathermap.org/forecast5#name5'
+
+            param :city, required: true, desc: 'City name'
+            param :country_code, desc: 'ISO 3166 2-letter country code'
+          end
+
+          endpoint :city_id, '?id={city_id}' do
+            desc %Q{
+              Current weather by city id. Recommended by OpenWeatherMap
+              docs.
+
+              List of city ID city.list.json.gz can be downloaded at
+              http://bulk.openweathermap.org/sample/
+            }
+
+            docs 'http://openweathermap.org/forecast5#cityid5'
+
+            param :city_id, required: true, desc: 'City ID (as defined by OpenWeatherMap)'
+          end
+
+          endpoint :location, '?lat={lat}&lon={lng}' do
+            desc %Q{
+              Weather forecast by geographic coordinates.
+            }
+
+            docs 'http://openweathermap.org/forecast5#geo5'
+
+            param :lat, :to_f, required: true, desc: 'Latitude'
+            param :lng, :to_f, required: true, desc: 'Longitude'
+          end
+
+          post_process { |e|
+            e['city.coord'] = Geo::Coord.new(e['city.coord.lat'], e['city.coord.lon']) \
+              if e['city.coord.lat'] && e['city.coord.lon']
+          }
+          post_process('city.coord.lat') { nil }
+          post_process('city.coord.lon') { nil }
+        end
+
+        # OpenWeatherMap reports most of logical errors with HTTP code
+        # 200 and responses like {cod: "500", message: "Error message"}
+        post_process { |h|
+          !h.key?('cod') || (200..400).cover?(h['cod'].to_i) or
+            fail "#{h['cod']}: #{h['message']}"
+        }
+
+        WEATHER_POST_PROCESSOR = lambda do |*|
+          # Most of the time there is exactly one weather item...
+          # ...but sometimes there are two. So, flatterning them looks
+          # more reasonable than having DataTable of 1-2 rows.
+          post_process { |h|
+            h['weather2'] = h['weather'].last if h['weather'] && h['weather'].count > 1
+          }
+          post_process('weather', &:first)
+
+          post_process('dt', &Time.method(:at))
+          post_process('dt_txt') { nil } # TODO: we need cleaner way to say "remove this"
+          post_process('sys.sunrise', &Time.method(:at))
+          post_process('sys.sunset', &Time.method(:at))
+
+          # https://github.com/zverok/geo_coord promo here!
+          post_process { |e|
+            e['coord'] = Geo::Coord.new(e['coord.lat'], e['coord.lon']) if e['coord.lat'] && e['coord.lon']
+          }
+          post_process('coord.lat') { nil }
+          post_process('coord.lon') { nil }
+
+          # See http://openweathermap.org/weather-conditions#How-to-get-icon-URL
+          post_process('weather.icon') { |i| "http://openweathermap.org/img/w/#{i}.png" }
+        end
+
+        # For endpoints returning weather in one place
+        instance_eval(&WEATHER_POST_PROCESSOR)
+
+        # For endpoints returning list of weathers (forecast or several
+        # cities).
+        post_process_items('list', &WEATHER_POST_PROCESSOR)
+      end
+    end
+  end
+end