geocodio 1.0.1 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: e30b7374e1e8cb776ab35c399696392474e1c1a8
-  data.tar.gz: e6959a9f46466860519c940139d7550a18bf5725
+  metadata.gz: 527dfc5568d5e04687a5e77ed4be5a618f63d1f0
+  data.tar.gz: 511078ee7c3cfbd7d8002faf2b1e35fef9f8da3d
 SHA512:
-  metadata.gz: 86466ddda70124ebe8d17e5d6db87d4f043988b1b5a98e1071d016f23cca04ef1dc3d2b5e844b924f3076124f32f9db6d94c88a5ef71ca738abaf85cd02f9520
-  data.tar.gz: 0974281a783423bb1d97a866c5192a46dd7dbe54ede8aa979deed2d1daa38b814e698415cc882b74433ece98d1686d873a8451d624f6e5f71c66631989bacf4f
+  metadata.gz: ccc773caf2885c4801dd40b647e97b092830349f43fcea0a125325fa9be308da0faaef6416a01de3675b4d9f36ee6cbcf8718815774a3c1d895950d2b776c1ce
+  data.tar.gz: cffce0a8438f2016369ad80a839987941e45fccdb5aabc2490dc4499813da0731ad54f37989ceb8f0bac6f9b30dd289074c201516d2a284beccd793308e3e287

data/lib/geocodio/client.rb

@@ -4,9 +4,12 @@ require 'cgi'
 
 require 'geocodio/client/error'
 require 'geocodio/client/response'
+require 'geocodio/utils'
 
 module Geocodio
   class Client
+    include Geocodio::Utils
+
     CONTENT_TYPE = 'application/json'
     METHODS = {
       :get    => Net::HTTP::Get,
@@ -26,7 +29,7 @@ module Geocodio
     # is submitted to http://api.geocod.io/v1/geocode. Multiple addresses will
     # instead submit a POST request.
     #
-    # @param addresses [Array] one or more String addresses
+    # @param addresses [Array<String>] one or more String addresses
     # @return [Geocodio::Address, Array<Geocodio::AddressSet>] One or more Address Sets
     def geocode(*addresses)
       addresses = addresses.first if addresses.first.is_a?(Array)
@@ -40,6 +43,28 @@ module Geocodio
       end
     end
 
+    # Reverse geocodes one or more pairs of coordinates. Coordinate pairs may be
+    # specified either as a comma-separated "latitude,longitude" string, or as
+    # a Hash with :lat/:latitude and :lng/:longitude keys. If one pair of
+    # coordinates is specified, a GET request is submitted to
+    # http://api.geocod.io/v1/reverse. Multiple pairs of coordinates will
+    # instead submit a POST request.
+    #
+    # @param coordinates [Array<String>, Array<Hash>] one or more pairs of coordinates
+    # @return [Geocodio::Address, Array<Geocodio::AddressSet>] One or more Address Sets
+    def reverse_geocode(*coordinates)
+      coordinates = coordinates.first if coordinates.first.is_a?(Array)
+
+      if coordinates.size < 1
+        raise ArgumentError, 'You must provide coordinates to reverse geocode.'
+      elsif coordinates.size == 1
+        reverse_geocode_single(coordinates.first)
+      else
+        reverse_geocode_batch(coordinates)
+      end
+    end
+    alias :reverse :reverse_geocode
+
     # Sends a GET request to http://api.geocod.io/v1/parse to correctly dissect
     # an address into individual parts. As this endpoint does not do any
     # geocoding, parts missing from the passed address will be missing from the
@@ -61,24 +86,31 @@ module Geocodio
 
       def geocode_single(address)
         response  = get '/geocode', q: address
-        results   = response.body['results']
-        query     = response.body['input']['formatted_address']
-        addresses = results.map { |result| Address.new(result) }
+        addresses = parse_results(response)
+
+        AddressSet.new(address, *addresses)
+      end
+
+      def reverse_geocode_single(pair)
+        pair = normalize_coordinates(pair)
 
-        AddressSet.new(query, *addresses)
+        response  = get '/reverse', q: pair
+        addresses = parse_results(response)
+
+        AddressSet.new(pair, *addresses)
       end
 
       def geocode_batch(addresses)
-        response    = post '/geocode', {}, body: addresses
-        result_sets = response.body['results']
+        response = post '/geocode', {}, body: addresses
+
+        parse_nested_results(response)
+      end
 
-        result_sets.map do |result_set|
-          query     = result_set['response']['input']['formatted_address']
-          results   = result_set['response']['results']
-          addresses = results.map { |result| Address.new(result) }
+      def reverse_geocode_batch(pairs)
+        pairs.map! { |pair| normalize_coordinates(pair) }
+        response = post '/reverse', {}, body: pairs
 
-          AddressSet.new(query, *addresses)
-        end
+        parse_nested_results(response)
       end
 
       def request(method, path, options)

data/lib/geocodio/utils.rb

@@ -0,0 +1,26 @@
+module Geocodio
+  module Utils
+    def parse_results(response)
+      results   = response.body['results']
+      addresses = results.map { |result| Address.new(result) }
+    end
+
+    def parse_nested_results(response)
+      results = response.body['results']
+
+      results.map do |result_set|
+        results   = result_set['response']['results']
+        addresses = results.map { |result| Address.new(result) }
+
+        query = result_set['query']
+
+        AddressSet.new(query, *addresses)
+      end
+    end
+
+    def normalize_coordinates(coordinates)
+      return coordinates unless coordinates.is_a?(Hash)
+      coordinates.sort.map { |p| p[1] }.join(',')
+    end
+  end
+end

data/lib/geocodio/version.rb

@@ -1,8 +1,8 @@
 module Geocodio
   class Version
     MAJOR = 1
-    MINOR = 0
-    PATCH = 1
+    MINOR = 1
+    PATCH = 0
 
     def self.to_s
       [MAJOR, MINOR, PATCH].join('.')

data/spec/address_set_spec.rb

@@ -26,6 +26,6 @@ describe Geocodio::AddressSet do
   end
 
   it 'references the original query' do
-    expect(address_set.query).to eq('826 Howard St, San Francisco CA, 94103')
+    expect(address_set.query).to eq('826 Howard Street San Francisco CA 94103')
   end
 end

data/spec/client_spec.rb

@@ -1,8 +1,9 @@
 require 'spec_helper'
 
 describe Geocodio::Client do
-  let(:geocodio) { Geocodio::Client.new }
-  let(:address) { '54 West Colorado Boulevard Pasadena CA 91105' }
+  let(:geocodio)    { Geocodio::Client.new }
+  let(:address)     { '54 West Colorado Boulevard Pasadena CA 91105' }
+  let(:coordinates) { '34.145760590909,-118.15204363636' }
 
   it 'requires an API key' do
     VCR.use_cassette('invalid_key') do
@@ -27,6 +28,27 @@ describe Geocodio::Client do
     end
   end
 
+  context 'reverse geocoding a single address' do
+    it 'uses a string' do
+      VCR.use_cassette('reverse') do
+        addresses = geocodio.reverse_geocode(coordinates)
+
+        expect(addresses.size).to eq(3)
+        expect(addresses).to be_a(Geocodio::AddressSet)
+      end
+    end
+
+    it 'uses a hash' do
+      VCR.use_cassette('reverse') do
+        lat, lng = coordinates.split(',')
+        addresses = geocodio.reverse_geocode(latitude: lat, longitude: lng)
+
+        expect(addresses.size).to eq(3)
+        expect(addresses).to be_a(Geocodio::AddressSet)
+      end
+    end
+  end
+
   it 'geocodes multiple addresses' do
     VCR.use_cassette('batch_geocode') do
       addresses = [
@@ -41,4 +63,51 @@ describe Geocodio::Client do
       addresses.each { |address| expect(address).to be_a(Geocodio::AddressSet) }
     end
   end
+
+  context 'reverse geocoding multiple addresses' do
+    it 'uses strings' do
+      VCR.use_cassette('batch_reverse') do
+        coordinate_pairs = [
+          '37.331669,-122.03074',
+          '34.145760590909,-118.15204363636',
+          '37.7815,-122.404933'
+        ]
+
+        addresses = geocodio.reverse_geocode(*coordinate_pairs)
+
+        expect(addresses.size).to eq(3)
+        addresses.each { |address| expect(address).to be_a(Geocodio::AddressSet) }
+      end
+    end
+
+    it 'uses hashes' do
+      VCR.use_cassette('batch_reverse') do
+        coordinate_pairs = [
+          { latitude: 37.331669,       longitude: -122.03074 },
+          { latitude: 34.145760590909, longitude: -118.15204363636 },
+          { latitude: 37.7815,         longitude: -122.404933 }
+        ]
+
+        addresses = geocodio.reverse_geocode(*coordinate_pairs)
+
+        expect(addresses.size).to eq(3)
+        addresses.each { |address| expect(address).to be_a(Geocodio::AddressSet) }
+      end
+    end
+
+    it 'uses an arbitrary combination of strings and hashes' do
+      VCR.use_cassette('batch_reverse') do
+        coordinate_pairs = [
+          { latitude: 37.331669, longitude: -122.03074 },
+          '34.145760590909,-118.15204363636',
+          { latitude: 37.7815,   longitude: -122.404933 }
+        ]
+
+        addresses = geocodio.reverse_geocode(*coordinate_pairs)
+
+        expect(addresses.size).to eq(3)
+        addresses.each { |address| expect(address).to be_a(Geocodio::AddressSet) }
+      end
+    end
+  end
 end

data/spec/vcr_cassettes/batch_reverse.yml

@@ -0,0 +1,53 @@
+---
+http_interactions:
+- request:
+    method: post
+    uri: http://api.geocod.io/v1/reverse?api_key=secret_api_key
+    body:
+      encoding: UTF-8
+      string: "[\"37.331669,-122.03074\",\"34.145760590909,-118.15204363636\",\"37.7815,-122.404933\"]"
+    headers:
+      Accept:
+      - application/json
+      Accept-Encoding:
+      - gzip;q=1.0,deflate;q=0.6,identity;q=0.3
+      User-Agent:
+      - Ruby
+      Content-Type:
+      - application/json
+  response:
+    status:
+      code: 200
+      message: OK
+    headers:
+      Date:
+      - Mon, 03 Feb 2014 16:12:36 GMT
+      Server:
+      - Apache
+      X-Powered-By:
+      - PHP/5.4.24
+      Cache-Control:
+      - no-cache
+      Access-Control-Allow-Origin:
+      - "*"
+      Transfer-Encoding:
+      - chunked
+      Content-Type:
+      - application/json
+    body:
+      encoding: UTF-8
+      string: "{\"results\":[{\"query\":\"37.331669,-122.03074\",\"response\":{\"results\":[]}},{\"query\":\"34.145760590909,-118.15204363636\",\"response\":{\"results\":[{\"address_components\":{\"number\":\"43\",\"predirectional\":\"W\",\"street\":\"Colorado\",\"suffix\":\"Blvd\",\"city\":\"Pasadena\",\"state\":\"CA\",\"zip\":\"91105\"},\"formatted_address\":\"43
+        W Colorado Blvd, Pasadena, CA 91105\",\"location\":{\"lat\":34.145766,\"lng\":-118.15141},\"accuracy\":1},{\"address_components\":{\"number\":\"1\",\"predirectional\":\"N\",\"street\":\"De
+        Lacey\",\"suffix\":\"Ave\",\"city\":\"Pasadena\",\"state\":\"CA\",\"zip\":\"91103\"},\"formatted_address\":\"1
+        N De Lacey Ave, Pasadena, CA 91103\",\"location\":{\"lat\":34.145759,\"lng\":-118.15223},\"accuracy\":0},{\"address_components\":{\"number\":\"1\",\"predirectional\":\"S\",\"street\":\"De
+        Lacey\",\"suffix\":\"Ave\",\"city\":\"Pasadena\",\"state\":\"CA\",\"zip\":\"91105\"},\"formatted_address\":\"1
+        S De Lacey Ave, Pasadena, CA 91105\",\"location\":{\"lat\":34.145759,\"lng\":-118.15223},\"accuracy\":0}]}},{\"query\":\"37.7815,-122.404933\",\"response\":{\"results\":[{\"address_components\":{\"number\":\"177\",\"street\":\"5th\",\"suffix\":\"St\",\"city\":\"San
+        Francisco\",\"state\":\"CA\",\"zip\":\"94102\"},\"formatted_address\":\"177
+        5th St, San Francisco, CA 94102\",\"location\":{\"lat\":37.781925,\"lng\":-122.405466},\"accuracy\":0},{\"address_components\":{\"number\":\"861\",\"street\":\"Howard\",\"suffix\":\"St\",\"city\":\"San
+        Francisco\",\"state\":\"CA\",\"zip\":\"94103\"},\"formatted_address\":\"861
+        Howard St, San Francisco, CA 94103\",\"location\":{\"lat\":37.782831,\"lng\":-122.40325},\"accuracy\":0},{\"address_components\":{\"number\":\"900\",\"street\":\"Howard\",\"suffix\":\"St\",\"city\":\"San
+        Francisco\",\"state\":\"CA\",\"zip\":\"94103\"},\"formatted_address\":\"900
+        Howard St, San Francisco, CA 94103\",\"location\":{\"lat\":37.7815,\"lng\":-122.404933},\"accuracy\":0}]}}]}"
+    http_version: 
+  recorded_at: Mon, 03 Feb 2014 16:12:38 GMT
+recorded_with: VCR 2.8.0

data/spec/vcr_cassettes/geocode.yml

@@ -19,7 +19,7 @@ http_interactions:
       message: OK
     headers:
       Date:
-      - Sun, 02 Feb 2014 17:40:52 GMT
+      - Mon, 03 Feb 2014 16:11:04 GMT
       Server:
       - Apache
       X-Powered-By:
@@ -39,5 +39,5 @@ http_interactions:
         W Colorado Blvd, Pasadena, CA 91105\",\"location\":{\"lat\":34.145760590909,\"lng\":-118.15204363636},\"accuracy\":1},{\"address_components\":{\"number\":\"54\",\"predirectional\":\"W\",\"street\":\"Colorado\",\"suffix\":\"Blvd\",\"city\":\"Pasadena\",\"state\":\"CA\",\"zip\":\"91105\"},\"formatted_address\":\"54
         W Colorado Blvd, Pasadena, CA 91105\",\"location\":{\"lat\":34.1457634625,\"lng\":-118.15170725},\"accuracy\":0.8}]}"
     http_version: 
-  recorded_at: Sun, 02 Feb 2014 17:40:53 GMT
+  recorded_at: Mon, 03 Feb 2014 16:11:05 GMT
 recorded_with: VCR 2.8.0

data/spec/vcr_cassettes/reverse.yml

@@ -0,0 +1,45 @@
+---
+http_interactions:
+- request:
+    method: get
+    uri: http://api.geocod.io/v1/reverse?api_key=secret_api_key&q=34.145760590909,-118.15204363636
+    body:
+      encoding: US-ASCII
+      string: ''
+    headers:
+      Accept:
+      - application/json
+      Accept-Encoding:
+      - gzip;q=1.0,deflate;q=0.6,identity;q=0.3
+      User-Agent:
+      - Ruby
+  response:
+    status:
+      code: 200
+      message: OK
+    headers:
+      Date:
+      - Mon, 03 Feb 2014 16:12:36 GMT
+      Server:
+      - Apache
+      X-Powered-By:
+      - PHP/5.4.24
+      Cache-Control:
+      - no-cache
+      Access-Control-Allow-Origin:
+      - "*"
+      Transfer-Encoding:
+      - chunked
+      Content-Type:
+      - application/json
+    body:
+      encoding: UTF-8
+      string: "{\"results\":[{\"address_components\":{\"number\":\"43\",\"predirectional\":\"W\",\"street\":\"Colorado\",\"suffix\":\"Blvd\",\"city\":\"Pasadena\",\"state\":\"CA\",\"zip\":\"91105\"},\"formatted_address\":\"43
+        W Colorado Blvd, Pasadena, CA 91105\",\"location\":{\"lat\":34.145766,\"lng\":-118.15141},\"accuracy\":1},{\"address_components\":{\"number\":\"1\",\"predirectional\":\"N\",\"street\":\"De
+        Lacey\",\"suffix\":\"Ave\",\"city\":\"Pasadena\",\"state\":\"CA\",\"zip\":\"91103\"},\"formatted_address\":\"1
+        N De Lacey Ave, Pasadena, CA 91103\",\"location\":{\"lat\":34.145759,\"lng\":-118.15223},\"accuracy\":0},{\"address_components\":{\"number\":\"1\",\"predirectional\":\"S\",\"street\":\"De
+        Lacey\",\"suffix\":\"Ave\",\"city\":\"Pasadena\",\"state\":\"CA\",\"zip\":\"91105\"},\"formatted_address\":\"1
+        S De Lacey Ave, Pasadena, CA 91105\",\"location\":{\"lat\":34.145759,\"lng\":-118.15223},\"accuracy\":0}]}"
+    http_version: 
+  recorded_at: Mon, 03 Feb 2014 16:12:38 GMT
+recorded_with: VCR 2.8.0

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: geocodio
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.1.0
 platform: ruby
 authors:
 - David Celis
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-02-02 00:00:00.000000000 Z
+date: 2014-02-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: json
@@ -95,15 +95,18 @@ files:
 - lib/geocodio/client.rb
 - lib/geocodio/client/error.rb
 - lib/geocodio/client/response.rb
+- lib/geocodio/utils.rb
 - lib/geocodio/version.rb
 - spec/address_set_spec.rb
 - spec/address_spec.rb
 - spec/client_spec.rb
 - spec/spec_helper.rb
 - spec/vcr_cassettes/batch_geocode.yml
+- spec/vcr_cassettes/batch_reverse.yml
 - spec/vcr_cassettes/geocode.yml
 - spec/vcr_cassettes/invalid_key.yml
 - spec/vcr_cassettes/parse.yml
+- spec/vcr_cassettes/reverse.yml
 homepage: https://github.com/davidcelis/geocodio
 licenses:
 - MIT
@@ -134,6 +137,8 @@ test_files:
 - spec/client_spec.rb
 - spec/spec_helper.rb
 - spec/vcr_cassettes/batch_geocode.yml
+- spec/vcr_cassettes/batch_reverse.yml
 - spec/vcr_cassettes/geocode.yml
 - spec/vcr_cassettes/invalid_key.yml
 - spec/vcr_cassettes/parse.yml
+- spec/vcr_cassettes/reverse.yml