geonames_api 0.0.2 → 0.0.3

data/README.md

@@ -26,12 +26,14 @@ Or install it yourself as:
 
 ### FYI
 
-GeoNamesAPI uses conventions similar to Rails' ActiveRecord. If you add any features, please stick to `find` and `all` as the core query methods.
+GeoNamesAPI uses conventions similar (but not exactly the same) to Rails' ActiveRecord. If you add any features, please stick to `find` and `all` as the core query methods.
 
 The data is converted into the type implied by the content by default. If that isn't sufficient, let's create something more explicit for the exceptions.
 
 The GeoNamesAPI classes include getters and setters that are the GeoNames API field names converted dynamically to more rubyish names using Rails' ActiveSupport `underscore` method. If the API ever changes, the attributes of the classes will change.
 
+There are some extra methods in most of the key classes. Documentation is included below.
+
 ### Configuration
 
 The gem is setup to use the `demo` user account by default. You'll need to provide your own credentials for anything but a simple set of test searches.
@@ -47,19 +49,124 @@ The geonames api uses the ISO code of the country as its natural key.
 
     > GeoNamesAPI::Country.find("US")
     
-    => #<GeoNamesAPI::Country:0x007fd43503dfc0 @country_code="US", @country_name="United States", @currency_code="USD", @fips_code="US", @iso_numeric=840, @north=49.388611, @capital="Washington", @continent_name="North America", @area_in_sq_km=9629091.0, @languages="en-US,es-US,haw,fr", @iso_alpha3="USA", @continent="NA", @south=24.544245, @east=-66.954811, @geoname_id=6252001, @west=-124.733253, @population=310232863>
+    => #<GeoNamesAPI::Country:0x007fd43503dfc0
+          @country_code="US",
+          @country_name="United States",
+          @currency_code="USD",
+          @fips_code="US",
+          @iso_numeric=840,
+          @north=49.388611,
+          @capital="Washington",
+          @continent_name="North America",
+          @area_in_sq_km=9629091.0,
+          @languages="en-US,es-US,haw,fr",
+          @iso_alpha3="USA",
+          @continent="NA",
+          @south=24.544245,
+          @east=-66.954811,
+          @geoname_id=6252001,
+          @west=-124.733253,
+          @population=310232863
+        >
 
     > GeoNamesAPI::Country.all
     
     => ... array of GeoNamesAPI::Country instances
+    
+There are no additional methods offered for countries.
 
 ### Weather
 
-The geonames api uses the latitude and longitude of the place as the parameters for its weather service.
+The GeoNamesAPI uses the latitude and longitude of the place as the parameters for its weather service.
 
-    > GeoNamesAPI::Weather.find(41.88,-87.68)
+    > weather = GeoNamesAPI::Weather.find(41.88,-87.68)
+    
+    => #<GeoNamesAPI::Weather:0x007fab1c80dc10
+          @latitude=41.88,
+          @longitude=-87.68,
+          @weather_condition="n/a",
+          @clouds="few clouds",
+          @observation="KMDW 012051Z 28009KT 10SM FEW049 BKN070 11/M02 A2983 RMK AO2 SLP105 T01111022 55010",
+          @wind_direction=280,
+          @icao="KMDW",
+          @sea_level_pressure=1010.5,
+          @elevation=188,
+          @country_code="US",
+          @clouds_code="FEW",
+          @lng=-87.75,
+          @temperature=11.1,
+          @dew_point=-2.2,
+          @wind_speed=9,
+          @humidity=39,
+          @station_name="Chicago, Chicago Midway Airport",
+          @datetime="2012-11-01 20:51:00",
+          @lat=41.78333333333333
+        >
+    
+The following instance methods are also available:
+
+    > weather.geo_names_api_country
+    > weather.geo_names_api_time_zone
+    > weather.time_zone
+    > weather.at_local
+    > weather.at_utc
+    > weather.elevation_feet
+    > weather.elevation_meters
+    # fahrenheit and celcius versions of temps
+    > weather.temperature_f
+    > weather.temperature_c
+    > weather.dew_point_f
+    > weather.dew_point_c
+
+### TimeZone
+
+The GeoNamesAPI uses the latitude and longitude of the place as the parameters for its time zone service.
+
+    > time_zone = GeoNamesAPI::TimeZone.find(41.88,-87.68)
     
-    => #<GeoNamesAPI::Weather:0x007fab1c80dc10 @latitude=41.88, @longitude=-87.68, @weather_condition="n/a", @clouds="few clouds", @observation="KMDW 012051Z 28009KT 10SM FEW049 BKN070 11/M02 A2983 RMK AO2 SLP105 T01111022 55010", @wind_direction=280, @icao="KMDW", @sea_level_pressure=1010.5, @elevation=188, @country_code="US", @clouds_code="FEW", @lng=-87.75, @temperature=11.1, @dew_point="-2.2", @wind_speed=9, @humidity=39, @station_name="Chicago, Chicago Midway Airport", @datetime="2012-11-01 20:51:00", @lat=41.78333333333333>
+    => #<GeoNamesAPI::TimeZone:0x007fd4b24d7e00
+          @time="2012-11-02 12:04",
+          @country_name="United States",
+          @sunset="2012-11-02 17:42",
+          @raw_offset=-6,
+          @dst_offset=-5,
+          @country_code="US",
+          @gmt_offset=-6,
+          @lng=-87.68,
+          @sunrise="2012-11-02 07:25",
+          @timezone_id="America/Chicago",
+          @lat=41.88
+        >
+
+    # ActiveSupport::TimeZone instance
+    > time_zone.time_zone
+    # Local and UTC version of each time
+    > time_zone.sunset_local
+    > time_zone.sunset_utc
+    > time_zone.sunrise_local
+    > time_zone.sunrise_utc
+    > time_zone.time_local
+    > time_zone.time_utc
+
+### Wikipedia
+
+The GeoNamesAPI uses the latitude and longitude of the place as the parameters for its Wikipedia artical service.
+
+Please note the use of the `all` method with `GeoNamesAPI::Wikipedia`. It returns all of the articles that match. The `find` method will return the first matching article.
+
+    > articles = GeoNamesAPI::Wikipedia.all(41.88,-87.68)
+    => [#<GeoNamesAPI::Wikipedia:0x007fd4b24e6040
+            @summary="Richard T. Crane Technical Preparatory High School, commonly known as Crane Tech Prep or Crane Tech High School, is a public high school in Chicago, Illinois. It is located at 2245 West Jackson Boulevard in Chicago's Near West Side community area.  (...)",
+            @distance=0.4108,
+            @rank=82,
+            @title="Crane High School (Chicago, Illinois)",
+            @wikipedia_url="en.wikipedia.org/wiki/Crane_High_School_%28Chicago%2C_Illinois%29",
+            @elevation=183,
+            @country_code="US",
+            @lng=-87.6827,
+            @lang="en",
+            @lat=41.8769>,
+          ...] 
 
 ### Others
 

data/lib/geonames_api.rb

@@ -3,9 +3,12 @@ require 'json'
 require 'active_support/all'
 require "geonames_api/version"
 require "geonames_api/hash"
+require "geonames_api/error"
 require "geonames_api/object"
 require "geonames_api/country"
 require "geonames_api/weather"
+require "geonames_api/time_zone"
+require "geonames_api/wikipedia"
 
 module GeoNamesAPI
   
@@ -27,6 +30,5 @@ module GeoNamesAPI
   def self.params
     { formatted: formatted, lang: lang, username: username, style: style }
   end
-  
-  
+    
 end

data/lib/geonames_api/country.rb

@@ -2,15 +2,7 @@ module GeoNamesAPI
   class Country < GeoNamesAPI::Object
 
     METHOD = "countryInfoJSON"
-    ID = ["country"]
-        
-    def self.all
-      where.collect { |response| new(response) }
-    end
-        
-    def self.where(params={})
-      JSON.load(open(url(params)).read)["geonames"]
-    end
+    ID = "country"        
 
   end
 end

data/lib/geonames_api/error.rb

@@ -0,0 +1,5 @@
+module GeoNamesAPI
+  class Error < StandardError
+    
+  end
+end

data/lib/geonames_api/object.rb

@@ -1,20 +1,56 @@
 module GeoNamesAPI
   class Object
+    
+    NESTED = true
         
     def self.find(*names)
-      params, n = {}, 0
-      self::ID.each { |i| params[i] = names[n]; n+= 1 }
-      new(where(params).first)
+      if response = where(name_params(names)).first
+        new(response)
+      end
+    end
+    
+    def self.all(*names)
+      where(name_params(names)).collect { |response| new(response) if response }.compact
+    end
+    
+    def self.where(params={})
+      response = JSON.load(open(url(params)).read)
+      case response.keys.first
+      when /\Astatus\Z/
+        message = response["status"]["message"]
+        raise GeoNamesAPI::Error, message[0,1].capitalize + message[1,message.length - 1]
+      end
+      if self::NESTED
+        [response.values].flatten
+      else
+        [response]
+      end
     end
     
     def self.url(params={})
       GeoNamesAPI.url + self::METHOD + GeoNamesAPI.params.merge(params).to_url
     end
+    
+    def self.name_params(names)
+      params, n = {}, 0
+      if names.any?
+        [self::ID].flatten.each { |i| params[i] = names[n]; n+= 1 }
+      end
+      params
+    end
 
     def initialize(response)
       parse(response)
     end 
 
+    def parse(response)
+      response.each do |key, value|
+        attr_name = create_attribute(key)
+        value = set_default_type(value)
+        send("#{attr_name}=", value)
+      end
+    end
+
     def create_attribute(attribute)
       attr_name = attribute.underscore.to_sym
       self.class.send(:attr_accessor, attr_name) unless respond_to?(attr_name)
@@ -23,22 +59,14 @@ module GeoNamesAPI
     
     def set_default_type(value)
       case value
-      when /\A\d+\Z/
+      when /\A-?\d+\Z/
         value.to_i
-      when /\A\d*\.\d*\Z/
+      when /\A-?\d*\.\d*\Z/
         value.to_f
       else
         value
       end
     end
-    
-    def parse(response)
-      response.each do |key, value|
-        attr_name = create_attribute(key)
-        value = set_default_type(value)
-        send("#{attr_name}=", value)
-      end 
-    end
-     
+         
   end
 end

data/lib/geonames_api/time_zone.rb

@@ -0,0 +1,31 @@
+module GeoNamesAPI
+  class TimeZone < GeoNamesAPI::Object
+    
+    METHOD = "timezoneJSON"
+    ID = ["lat", "lng"]
+    NESTED = false
+    
+    def time_zone
+      ActiveSupport::TimeZone.new(timezone_id)
+    end
+    
+    def local(time_type)
+      t = DateTime.parse(send(time_type))
+      time_zone.local(t.year, t.month, t.day, t.hour, t.minute)
+    end
+    
+    def utc(time_type)
+      local(time_type).utc
+    end
+    
+    def method_missing(method, *args)
+      case method
+      # Provides the local and utc time variant of each time
+      # Examples: time_zone.sunrise_local, time_zone.time_utc
+      when /\A(.*)_(local|utc)\Z/
+        send($2, $1)
+      end
+    end
+    
+  end
+end

data/lib/geonames_api/version.rb

@@ -1,3 +1,3 @@
 module GeoNamesAPI
-  VERSION = "0.0.2"
-end
+  VERSION = "0.0.3"
+end

data/lib/geonames_api/weather.rb

@@ -4,16 +4,53 @@ module GeoNamesAPI
     METHOD = "findNearByWeatherJSON"
     ID = ["lat", "lng"]
     
-    def self.where(params={})
-      JSON.load(open(url(params)).read)["weatherObservation"]
+    def geo_names_api_country
+      @geo_names_api_country ||= GeoNamesAPI::Country.find(country_code)
     end
     
-    def self.url(params)
-      GeoNamesAPI.url + METHOD + GeoNamesAPI.params.merge(params).to_url
+    def geo_names_api_time_zone
+      @geo_names_api_time_zone ||= GeoNamesAPI::TimeZone.find(lat, lng)
+    end
+    
+    def time_zone
+      geo_names_api_time_zone.time_zone
+    end
+        
+    def at_local
+      t = DateTime.parse(datetime)
+      time_zone.local(t.year, t.month, t.day, t.hour, t.minute)
+    end
+    
+    def at_utc
+      at_local.utc
+    end
+    
+    def elevation_feet
+      elevation * 3.28084
+    end
+    
+    def elevation_meters
+      elevation
+    end
+        
+    def convert_c_to_f(temp)
+      temp * 9.to_f / 5.to_f + 32
     end
 
-    def initialize(response)
-      parse(response)
+    def temperature_f
+      convert_c_to_f(temperature)
+    end
+    
+    def temperature_c
+      temperature
+    end
+    
+    def dew_point_f
+      convert_c_to_f(dew_point)
+    end
+    
+    def dew_point_c
+      dew_point
     end
     
   end

data/lib/geonames_api/wikipedia.rb

@@ -0,0 +1,8 @@
+module GeoNamesAPI
+  class Wikipedia < GeoNamesAPI::Object
+    
+    METHOD = "findNearbyWikipediaJSON"
+    ID = %W(lat lng)
+    
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: geonames_api
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.3
   prerelease: 
 platform: ruby
 authors:
@@ -43,10 +43,13 @@ files:
 - geonames_api.gemspec
 - lib/geonames_api.rb
 - lib/geonames_api/country.rb
+- lib/geonames_api/error.rb
 - lib/geonames_api/hash.rb
 - lib/geonames_api/object.rb
+- lib/geonames_api/time_zone.rb
 - lib/geonames_api/version.rb
 - lib/geonames_api/weather.rb
+- lib/geonames_api/wikipedia.rb
 homepage: https://github.com/buytruckload/geonames_api
 licenses: []
 post_install_message: