zippopotamus-client 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: a5f89966abe53d876bcdfbcbd687ce0b906e16a0
-  data.tar.gz: f12e8db0fc202bca323b0ab5a77b680b2de63820
+  metadata.gz: e3e72598e65c0ff2df1de29a6435926061d3b6f0
+  data.tar.gz: 394c60a29a616ac5d21e6f7bc99602e073c41dbe
 SHA512:
-  metadata.gz: 73258d385e23038417f55de799cb898df42853e3e95b8551d113f16108b13a76f93fc302f28512dc63f4072f89631f9e13fd367b9b235de38d979acd19375a05
-  data.tar.gz: 6679c078a4eac07a8909d4f3a7cdbec505b3a2035113053514324273627b302c4135b2ebaf23437d34d591515222d88dfcde48a7425d3c1f50170207111bbffd
+  metadata.gz: 4a088555a63585b8defd7fd67e8f70babe0a651b72e0e1cfcae5467d3463e155fe6575186fe51977015b2949a82ed01ff8cb23f9ee84a3de0c2ded1088663eae
+  data.tar.gz: ceadb522ff23a41bb2a6aac5dd54ba50fdc57cd19e30f8c022d1fddad9ce9e09c81dd57ecb602b7113f84ef127176aaaa67619dd955efa8588db0bcb505b33d0

data/.gitignore

@@ -6,6 +6,7 @@
 zeus.json
 custom_plan.rb
 database.yml
+pkg/
 
 # Ignore all logfiles and tempfiles.
 /log/*.log

data/README.md

@@ -3,16 +3,22 @@
 This is a simple ruby client for the [zippopotam.us](http://zippopotam.us) API.
 It uses [excon](https://github.com/geemus/excon) http client for it's speed and persistent connections support.
 
+[![Gem Version](https://badge.fury.io/rb/zippopotamus-client.png)](http://badge.fury.io/rb/zippopotamus-client)
+
+
 ## Installation
 
-Add this line to your application's Gemfile (only available through github for the moment):
+Add this line to your application's Gemfile:
 
-    gem 'zippopotamus-client', github: 'rcugut/zippopotamus-ruby-client'
+    gem 'zippopotamus-client'
 
 And then execute:
 
     $ bundle
 
+Or install the gem via command line:
+
+    $ gem install zippopotamus-client
 
 
 ## Usage
@@ -20,53 +26,54 @@ And then execute:
 #### Configure
 
 ```ruby
+require 'zippopotamus'
 
-    require 'zippopotamus'
-
-    Zippopotamus.configure do |c|
-      # enable `use_persistent_connection` to keep the connection alive between subsequent calls
-      c.use_persistent_connection = false # default: true
-    end
+Zippopotamus.configure do |c|
+  # enable `use_persistent_connection` to keep the connection alive between subsequent calls
+  c.use_persistent_connection = false # default: true
+end
 ```
 
-#### Use it
+#### Use
 
 ```ruby
-    
-    # Lookup a zip code by default in US 
-    Zippopotamus.lookup_postal_code('90210')
+# Lookup a zip code (by default country = US)
+place = Zippopotamus.lookup_postcode('90210')
+# or the alias method lookup_zipcode
+place = Zippopotamus.lookup_zipcode('90210')
 
-    # returns a Zippopotamus::Place
-    #    @name: 'Beverly Hills'
-    #    @region: 'California'
-    #    @region_code: 'CA'
-    #    @latitude: 34.0901
-    #    @longitude: -118.4065
-    #    @alternatives: []
-    #    #has_alternatives?: false
+# place is a <Zippopotamus::Place>
+#    @postcode: '90210'
+#    @name: 'Beverly Hills'
+#    @region: 'California'
+#    @region_code: 'CA'
+#    @latitude: 34.0901
+#    @longitude: -118.4065
+#    @alternatives: []
+#    #has_alternatives?: false
 
 
 
-    # Lookup a postal code in France, with multiple place results (alternatives)
-    place = Zippopotamus.lookup_postal_code('01000', 'fr')
+# Lookup a postcode in France, with multiple place results (alternatives)
+place = Zippopotamus.lookup_postcode('01000', 'fr')
 
-    # returns the first Place in the list of multiple places
-    puts place.name
-    #> 'Bourg-en-Bresse'
+# returns the first Place in the list of multiple places
+puts place.name
+#> 'Bourg-en-Bresse'
 
-    # this place has alternatives (with same postal_code)
-    puts place.has_alternatives?
-    #> true
+# this place has alternatives (with same postal_code)
+puts place.has_alternatives?
+#> true
 
-    # get array of Zippotamus::Place representing alternatives (with the same postal_code)
-    puts place.alternatives
-    #> [#<Place @name="Saint-Denis-lès-Bourg", @region="Rhône-Alpes", @region_code="B9", @latitude=46.2022, @longitude=5.1892>]
+# get array of Zippotamus::Place representing alternatives (with the same postcode)
+puts place.alternatives
+#> [#<Place @name="Saint-Denis-lès-Bourg", @region="Rhône-Alpes", @region_code="B9", @latitude=46.2022, @longitude=5.1892>]
 
 
 
-    # Works if postal code is a number (although not recommended)
-    Zippopotamus.lookup_postal_code(90210)
-    #=> #<Place @name="Beverly Hills", @region="California", @region_code="CA", @latitude=34.0901, @longitude=-118.4065, @alternatives=[]>
+# Works if postcode is a number (although not recommended)
+Zippopotamus.lookup_postcode(90210)
+#=> #<Place @name="Beverly Hills", @region="California", @region_code="CA", @latitude=34.0901, @longitude=-118.4065, @alternatives=[]>
 ```
 
 
@@ -79,3 +86,7 @@ And then execute:
 5. Create new Pull Request
 
 
+## Special thanks
+
+Special thanks to [zippopotam.us](http://zippopotam.us) project for the postal codes database and API hosting/maintenance
+

data/lib/zippopotamus.rb

@@ -12,17 +12,13 @@ require 'zippopotamus/client'
 #
 #
 #
-# Usage
+# Use
 #
 #   # Lookup US zip codes by default
-#   Zippopotamus.lookup_postal_code('90210')
+#   Zippopotamus.lookup_postcode('90210')
 #
 #   # Specify country by 2 letter code
-#   Zippopotamus.lookup_postal_code('01000', 'fr')
-#
-#
-#   # Raise an error when parameters are invalid
-#   Zippopotamus.lookup_postal_code(12345)
+#   Zippopotamus.lookup_postcode('01000', 'fr')
 #
 module Zippopotamus
 
@@ -33,18 +29,19 @@ module Zippopotamus
   end
 
 
-  # lookup a postal_code for a country and return the place(s) for it
+  # lookup a postcode for a country and return the place(s) for it
   #
-  # @param [String] postal_code
+  # @param [String] postcode
   # @param [String] country 2 letter country code (default: 'us')
   # @return [Zippopotamus::Place] place with postal_code for country OR nil if not found
   # @raise if invalid parameters
-  def lookup_postal_code(postal_code, country = 'us')
+  def lookup_postcode(postcode, country = 'us')
     @client ||= Zippopotamus::Client.new(get_configuration.use_persistent_connection)
-    return @client.lookup_postal_code(postal_code, country)
+    return @client.lookup_postcode(postcode, country)
   end
 
-
+  alias_method :lookup_zipcode, :lookup_postcode
+  alias_method :lookup_postal_code, :lookup_postcode
 
   private
 

data/lib/zippopotamus/client.rb

@@ -12,21 +12,21 @@ module Zippopotamus
 
 
 
-    # @param [String] postal_code
+    # @param [String] postcode
     # @param [String] country 2 letter country code (default: 'us')
-    def lookup_postal_code(postal_code, country = 'us')
-      postal_code = postal_code.to_s if postal_code.is_a?(Integer)
-      raise "Invalid postal_code parameter: '#{postal_code}'" if not_blank_string?(postal_code)
+    def lookup_postcode(postcode, country = 'us')
+      postcode = postcode.to_s if postcode.is_a?(Integer)
+      raise "Invalid postcode parameter: '#{postcode}'" if not_blank_string?(postcode)
       raise "Invalid country parameter: '#{country}'" if not_blank_string?(country) || country.length != 2
       country = country.downcase
       begin
-        r = @connection.get(path: "/#{country}/#{postal_code}")
+        r = @connection.get(path: "/#{country}/#{postcode}")
       rescue Excon::Errors::SocketError
         # just retry
-        r = @connection.get(path: "/#{country}/#{postal_code}")
+        r = @connection.get(path: "/#{country}/#{postcode}")
       end
       if r.status == 200
-        return Place.new(*JSON.parse(r.body)['places'])
+        return Place.new(postcode, *JSON.parse(r.body)['places'])
       else
         return nil
       end
@@ -47,11 +47,12 @@ module Zippopotamus
 
   class Place
 
-    attr_reader :name, :region, :region_code, :latitude, :longitude
+    attr_reader :postcode, :name, :region, :region_code, :latitude, :longitude
     attr_reader :alternatives
 
-    def initialize(*places)
+    def initialize(postcode, *places)
       place = places.shift
+      @postcode = postcode
       @name = place['place name']
       @region = place['state']
       @region_code = place['state abbreviation']
@@ -60,7 +61,7 @@ module Zippopotamus
 
       @alternatives = []
       places.each do |place|
-        @alternatives << Place.new(place)
+        @alternatives << Place.new(postcode, place)
       end
       @alternatives.freeze
     end

data/lib/zippopotamus/version.rb

@@ -1,3 +1,3 @@
 module Zippopotamus
-  VERSION = "0.1.1"
+  VERSION = "0.2.0"
 end

data/spec/place_spec.rb

@@ -3,16 +3,17 @@ require 'json'
 
 describe Zippopotamus::Place do
 
-  DATA_WO_ALTERNATIVES = [{"place name"=>"Beverly Hills", "longitude"=>"-118.4065", "state"=>"California", "state abbreviation"=>"CA", "latitude"=>"34.0901"}]
-  DATA_WITH_ALTERNATIVES = [{"place name"=>"Bourg-en-Bresse", "longitude"=>"5.2258", "state"=>"Rhône-Alpes", "state abbreviation"=>"B9", "latitude"=>"46.2057"},
-                            {"place name"=>"Saint-Denis-lès-Bourg", "longitude"=>"5.1892", "state"=>"Rhône-Alpes", "state abbreviation"=>"B9", "latitude"=>"46.2022"}]
+  DATA_SINGLE_PLACE = [{"place name"=>"Beverly Hills", "longitude"=>"-118.4065", "state"=>"California", "state abbreviation"=>"CA", "latitude"=>"34.0901"}]
+  DATA_MULTI_PLACE = [{"place name"=>"Bourg-en-Bresse", "longitude"=>"5.2258", "state"=>"Rhône-Alpes", "state abbreviation"=>"B9", "latitude"=>"46.2057"},
+                      {"place name"=>"Saint-Denis-lès-Bourg", "longitude"=>"5.1892", "state"=>"Rhône-Alpes", "state abbreviation"=>"B9", "latitude"=>"46.2022"}]
 
-  context "with no alternative places" do
+  context "with single place" do
     before do
-      @place = Zippopotamus::Place.new(*DATA_WO_ALTERNATIVES)
+      @place = Zippopotamus::Place.new('90210', *DATA_SINGLE_PLACE)
     end
 
     it "is a valid Place without alternatives" do
+      @place.postcode.should == '90210'
       @place.name.should == 'Beverly Hills'
       @place.region.should == 'California'
       @place.region_code.should == 'CA'
@@ -25,19 +26,21 @@ describe Zippopotamus::Place do
 
   context "with multiple alternative places" do
     before do
-      @place = Zippopotamus::Place.new(*DATA_WITH_ALTERNATIVES)
+      @place = Zippopotamus::Place.new('01000', *DATA_MULTI_PLACE)
     end
 
     it "is a valid Place without alternatives" do
+      @place.postcode.should == '01000'
       @place.name.should == 'Bourg-en-Bresse'
       @place.region.should == 'Rhône-Alpes'
       @place.region_code.should == 'B9'
       @place.has_alternatives?.should be_true
     end
 
-    it "has valid values for alternative Place" do
+    it "has valid values for alternative Places" do
       place1 = @place.alternatives[0]
       place1.should be_a(Zippopotamus::Place)
+      place1.postcode.should == '01000'
       place1.name.should == 'Saint-Denis-lès-Bourg'
       place1.region.should == 'Rhône-Alpes'
       place1.region_code.should == 'B9'

data/spec/zippopotamus_spec.rb

@@ -7,12 +7,13 @@ describe Zippopotamus do
     context "valid postal_code with single Place returned" do
       before do
         VCR.use_cassette 'us_90210' do
-          @result = Zippopotamus.lookup_postal_code!('90210')
+          @result = Zippopotamus.lookup_zipcode('90210')
         end
       end
 
       it "returns correct data" do
         @result.should be_a(Zippopotamus::Place)
+        @result.postcode.should == '90210'
         @result.name.should == 'Beverly Hills'
         @result.region.should == 'California'
         @result.region_code.should == 'CA'
@@ -26,7 +27,7 @@ describe Zippopotamus do
     context "valid postal_code with multiple Places returned" do
       before do
         VCR.use_cassette 'fr_01000' do
-          @result = Zippopotamus.lookup_postal_code!('01000', 'fr')
+          @result = Zippopotamus.lookup_postcode('01000', 'fr')
         end
       end
 
@@ -62,14 +63,15 @@ describe Zippopotamus do
 
 
 
-  context "live HTTP tests with US/90210 valid data" do
+  context "live HTTP tests with US/90210" do
 
     before do
-      @result = Zippopotamus.lookup_postal_code!('90210')
+      @result = Zippopotamus.lookup_zipcode('90210')
     end
 
     it "returns correct data" do
       @result.should be_a(Zippopotamus::Place)
+      @result.postcode.should == '90210'
       @result.name.should == 'Beverly Hills'
       @result.region.should == 'California'
       @result.region_code.should == 'CA'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: zippopotamus-client
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
 platform: ruby
 authors:
 - Radu Cugut
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-01-13 00:00:00.000000000 Z
+date: 2014-01-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake