gmaps_geocoding 0.0.4 → 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: e0eb2ba63ab2f125d3002741bcb198fe93d5f880
+  data.tar.gz: df00924a0a27c88b2976db2f03d09611aa8b6190
+SHA512:
+  metadata.gz: 79a5ff100b66ecb148e30babe4a8003e09746603a225ffcdb0b0bae4481e23171d76f7e3336503922ccf69e26d041df618b387f4f76ba27e3686dcf57a13e1d2
+  data.tar.gz: 1bcb5295f1e08aac1a9778b998cddadb1f2c3c4cc191e92ba28848b06f3267cb41c86105a371307cc215544bbc3add7ec99740620edb589f00ca62b94d9b90b3

data/.ruby-version

@@ -1 +1 @@
-ruby-1.9.3-p392@gmaps_geocoding
+ruby-2.0.0@gmaps_geocoding

data/.versions.conf

@@ -1,4 +1,4 @@
-ruby=ruby-1.9.3-p392
+ruby=ruby-2.0.0
 ruby-gemset=gmaps_geocoding
 #ruby-gem-install=bundler rake
 #ruby-bundle-install=true

data/.yardopts

@@ -0,0 +1,2 @@
+--main README.md
+--no-private

data/Gemfile

@@ -2,3 +2,5 @@ source 'https://rubygems.org'
 
 # Specify your gem's dependencies in gmaps_geocoding.gemspec
 gemspec
+
+gem 'simplecov', :require => false, :group => :test

data/README.md

@@ -11,11 +11,11 @@ Add this line to your application's Gemfile:
 
 And then execute:
 
-    $ bundle
+    bundle
 
 Or install it yourself as:
 
-    $ gem install gmaps_geocoding
+    gem install gmaps_geocoding
 
 ## Usage
 ### Global information

data/Rakefile

@@ -1,6 +1,7 @@
 # encoding: utf-8
 require 'bundler/gem_tasks'
 require 'rake/testtask'
+require 'yard'
 
 lib = File.expand_path('../lib/', __FILE__)
 $:.unshift lib unless $:.include?(lib)
@@ -24,8 +25,14 @@ end
 
 Rake::TestTask.new do |t|
   t.libs << 'lib/gmaps_geocoding'
-  t.test_files = FileList['test/*_test.rb']
+  t.test_files = FileList['test/**/*_test.rb']
   t.verbose = true
 end
 
+desc 'Generate documentation'
+YARD::Rake::YardocTask.new do |t|
+  t.files   = ['lib/**/*.rb', '-', 'LICENSE.txt']
+  t.options = ['--main', 'README.md', '--no-private']
+end
+
 task default: :test

data/gmaps_geocoding.gemspec

@@ -23,8 +23,9 @@ Gem::Specification.new do |s|
 
   s.add_runtime_dependency 'rest-client', '~> 1.6.7'
   s.add_runtime_dependency 'yajl-ruby', '~> 1.1.0'
-  s.add_runtime_dependency 'nori', '~> 2.0.4'
-  s.add_runtime_dependency 'nokogiri', '>= 1.4.0'
-  s.add_development_dependency 'bundler', '~> 1.3'
+  s.add_runtime_dependency 'nori', '~> 2.2.0'
+  s.add_runtime_dependency 'nokogiri', '~> 1.6.0'
+  s.add_development_dependency 'bundler', '~> 1.3.5'
   s.add_development_dependency 'rake'
+  s.add_development_dependency 'yard'
 end

data/lib/gmaps_geocoding/api.rb

@@ -1,6 +1,12 @@
 # encoding: utf-8
 
 module GmapsGeocoding
+  # Google Maps Geocoding Service abstraction class
+  #
+  # @example
+  #  opts = {address: 'Tour Eiffel, Paris, IDF, France', output: 'json'}
+  #  api = GmapsGeocoding::Api.new(opts)
+  #
   class Api
     attr_reader :config
 
@@ -8,12 +14,21 @@ module GmapsGeocoding
       @config = Config.new(opts)
     end
 
+    # Return a Ruby Hash object of the Google Maps Geocoding Service response
+    #
+    # {https://developers.google.com/maps/documentation/geocoding/ Google Maps Geocoding Service documentation}.
+    #
+    # @example
+    #  # json output example
+    #  opts = {address: 'Tour Eiffel, Paris, IDF, France', output: 'json'}
+    #  api = GmapsGeocoding::Api.new(opts)
+    #  result = api.get_location
+    #  # xml output example
+    #  opts = {address: 'Tour Eiffel, Paris, IDF, France', output: 'xml'}
+    #  api = GmapsGeocoding::Api.new(opts)
+    #  result = api.get_location
+    #
     def get_location
-      get_gmaps_data
-    end
-
-    private
-    def get_gmaps_data
       begin
         if @config.valid?
           rest_client = retrieve_geocoding_data
@@ -21,7 +36,6 @@ module GmapsGeocoding
                      when true
                        GmapsGeocoding.from_json(rest_client.to_s)
                      else
-                       # Xml parser
                        GmapsGeocoding.from_xml(rest_client.to_s)
                    end
           return result
@@ -32,6 +46,44 @@ module GmapsGeocoding
       nil
     end
 
+    # Get the best latlng for an address based on Google Maps Geocoder "location_type"
+    #
+    # location_type stores additional data about the specified location. The following values are currently supported:
+    #   google.maps.GeocoderLocationType.ROOFTOP            indicates that the returned result reflects a precise geocode.
+    #   google.maps.GeocoderLocationType.RANGE_INTERPOLATED indicates that the returned result reflects an approximation (usually on a road) interpolated between two precise points (such as intersections). Interpolated results are generally returned when rooftop geocodes are unavailable for a street address.
+    #   google.maps.GeocoderLocationType.GEOMETRIC_CENTER   indicates that the returned result is the geometric center of a result such as a polyline (for example, a street) or polygon (region).
+    #   google.maps.GeocoderLocationType.APPROXIMATE        indicates that the returned result is approximate.
+    #
+    # @example
+    #  # json output example
+    #  opts = {address: 'Tour Eiffel, Paris, IDF, France', output: 'json'}
+    #  api = GmapsGeocoding::Api.new(opts)
+    #  data = api.get_location
+    #  if data.include?('status') && data['status'].eql?('OK') # or more simple : if data.include?('results')
+    #    return get_finest_latlng(data['results']) # output : [2.291018, 48.857269]
+    #  end
+    #
+    # @param data_result [Array] The json#results or xml#result array from {#get_location} method
+    # @return [Array] array contains latitude and longitude of the location
+    def get_finest_latlng(data_result)
+      tmp_result = {}
+      data = data_result
+      data.each do |d|
+        tmp_result["#{d['geometry']['location_type']}"] = {lng: d['geometry']['location']['lng'].to_f,
+                                                       lat: d['geometry']['location']['lat'].to_f}
+      end
+      if tmp_result.include?('ROOFTOP')
+        [tmp_result['ROOFTOP'][:lng], tmp_result['ROOFTOP'][:lat]]
+      elsif tmp_result.include?('RANGE_INTERPOLATED')
+        [tmp_result['RANGE_INTERPOLATED'][:lng], tmp_result['RANGE_INTERPOLATED'][:lat]]
+      elsif tmp_result.include?('GEOMETRIC_CENTER')
+        [tmp_result['GEOMETRIC_CENTER'][:lng], tmp_result['GEOMETRIC_CENTER'][:lat]]
+      else
+        [tmp_result['APPROXIMATE'][:lng], tmp_result['APPROXIMATE'][:lat]]
+      end
+    end
+
+    private
     def build_url_query
       query = {}
       query[:address]    = @config.address    if @config.address
@@ -47,24 +99,25 @@ module GmapsGeocoding
 
     def retrieve_geocoding_data
       require 'rest-client'
-      data = build_url_query
+      data = build_url_query()
       RestClient.get data[:url], params: data[:query]
     end
   end
 
-  def self.from_json(json)
-    require 'yajl/json_gem'
-    Yajl::Parser.parse(json)
-  end
+  class << self
+    def from_json(json)
+      require 'yajl/json_gem'
+      Yajl::Parser.parse(json)
+    end
 
-  def self.from_xml(xml)
-    require 'nori'
-    n = Nori.new(parser: :nokogiri).parse(xml)
-    if n.include?('GeocodeResponse')
-      n = n['GeocodeResponse']
-    else
-      n = {'status' => 'UNKNOWN_ERROR'}
+    def from_xml(xml)
+      require 'nori'
+      result = Nori.new(parser: :nokogiri).parse(xml)
+      if result.include?('GeocodeResponse')
+        result['GeocodeResponse']
+      else
+        {status: 'UNKNOWN_ERROR'}
+      end
     end
-    n
   end
 end

data/lib/gmaps_geocoding/config.rb

@@ -1,9 +1,8 @@
 # encoding: utf-8
 
 module GmapsGeocoding
+  # Configuration class for GmapsGeocoding API.
   class Config
-    attr_reader :options
-
     def initialize(opts = {})
       @options = {url: 'https://maps.googleapis.com/maps/api/geocode'}
       @options[:output]     = ENV['GOOGLE_MAPS_GEOCODING_OUTPUT']     || opts[:output]     || 'json'
@@ -17,61 +16,108 @@ module GmapsGeocoding
       @options.merge!(opts).reject!{|_, v| v.to_s.length == 0 }
     end
 
+    # URL of the Google Maps Geocoding Service
+    #
+    # @return [String] URL of the Google Maps Geocoding Service
     def url
       @options[:url]
     end
 
+    # Output format of the Google Maps Geocoding Service
+    #
+    # @return [String] Output format of the Google Maps Geocoding Service. Only _xml_ or _json_ formats are available
     def output
       @options[:output]
     end
 
+    # The address that you want to geocode
+    #
+    # @return [String] The address that you want to geocode.
     def address
       @options[:address]
     end
 
+    # The textual latitude/longitude value for which you wish to obtain the closest, human-readable address
+    #
+    # @example
+    #  "40.714224,-73.961452"
+    #
+    # @return [String] The textual latitude/longitude value for which you wish to obtain the closest, human-readable address
     def latlng
       @options[:latlng]
     end
-
+    # A component filter for which you wish to obtain a geocode
+    #
+    # {https://developers.google.com/maps/documentation/geocoding/#ComponentFiltering}
+    # @return [String] A component filter for which you wish to obtain a geocode
     def components
       @options[:components]
     end
 
+    # Indicates whether or not the geocoding request comes from a device with a location sensor.
+    #
+    # @return [String] Indicates whether or not the geocoding request comes from a device with a location sensor. Must be either "true" or "false".
     def sensor
       @options[:sensor]
     end
 
+    # The bounding box of the viewport within which to bias geocode results more prominently
+    #
+    # {https://developers.google.com/maps/documentation/geocoding/#Viewports}
+    # @return [String] The bounding box of the viewport within which to bias geocode results more prominently
     def bounds
       @options[:bounds]
     end
 
+    # The language in which to return results
+    #
+    # @return [String] The language in which to return results. {https://developers.google.com/maps/faq#languagesupport Supported languages}.
     def language
       @options[:language]
     end
 
+    # The region code, specified as a ccTLD ("top-level domain") two-character value
+    #
+    # {https://developers.google.com/maps/documentation/geocoding/#RegionCodes}
+    # @return [String] The region code, specified as a ccTLD ("top-level domain") two-character value
     def region
       @options[:region]
     end
 
+    # Check if the configuration object is valid
+    #
+    # @return [true, false] Return _true_ or _false_
     def valid?
-      return is_query_valid? &&
-          is_output_param_valid?
+      is_query_valid? && is_output_param_valid?
     end
 
+    # Check if the output format of the query is set to _json_
+    #
+    # @return [true, false] Return _true_ or _false_
     def is_json_format?
       'json'.eql?(output)
     end
 
+    # Check if the output format of the query is set to _xml_
+    #
+    # @return [true, false] Return _true_ or _false_
     def is_xml_format?
       'xml'.eql?(output)
     end
 
     private
+    # Check if the query is valid
+    #
+    # According to the specifications: {https://developers.google.com/maps/documentation/geocoding/#GeocodingRequests}
     def is_query_valid?
       (@options[:address].to_s.length > 0 && @options[:latlng].to_s.length == 0) ||
-          (@options[:address].to_s.length == 0 && @options[:latlng].to_s.length > 0)
+          (@options[:address].to_s.length == 0 && @options[:latlng].to_s.length > 0) ||
+          (@options[:components].to_s.length > 0)
     end
 
+    # Check if the output format is valid
+    #
+    # According to the specifications: {https://developers.google.com/maps/documentation/geocoding/#GeocodingResponses}
     def is_output_param_valid?
       ['json', 'xml'].include?(output)
     end

data/lib/gmaps_geocoding/version.rb

@@ -1,3 +1,3 @@
 module GmapsGeocoding
-  VERSION = '0.0.4'
+  VERSION = '0.1.0'
 end

data/test/gmaps_geocoding_test.rb

@@ -1,5 +1,6 @@
 # encoding: utf-8
 require 'test/unit'
+require_relative 'test_helper'
 require 'gmaps_geocoding'
 
 class GmapsGeocodingTest < Test::Unit::TestCase
@@ -7,45 +8,58 @@ class GmapsGeocodingTest < Test::Unit::TestCase
     config = GmapsGeocoding::Config.new
     assert_not_nil config
     assert_equal false, config.valid?
-    assert_equal 3, config.options.length
   end
 
   def test_config_address_set
     config = GmapsGeocoding::Config.new({address: 'Tour Eiffel, IDF, Paris, France'})
     assert_not_nil config
     assert_equal true, config.valid?
-    assert_equal 4, config.options.length
   end
 
    def test_config_latlng_set
     config = GmapsGeocoding::Config.new({latlng: '40.714224,-73.961452'})
     assert_not_nil config
     assert_equal true, config.valid?
-    assert_equal 4, config.options.length
   end
 
   def test_config_address_latlng_set
     config = GmapsGeocoding::Config.new({address: 'Tour Eiffel, IDF, Paris, France', latlng: '40.714224,-73.961452'})
     assert_not_nil config
     assert_equal false, config.valid?
-    assert_equal 5, config.options.length
+  end
+
+  def test_config_url
+    config = GmapsGeocoding::Config.new({url: 'http://fakeurl.com'})
+    assert_equal 'http://fakeurl.com', config.url
   end
 
   def test_api_json_set
     opts = {address: 'Tour Eiffel, Paris, IDF, France', output: 'json'}
     api = GmapsGeocoding::Api.new(opts)
-    result = api.get_location
     assert_not_nil api
-    assert_not_nil result
-    assert_equal 4, api.config.options.length
+
+    result_location = api.get_location
+    assert_not_nil result_location
+    assert_kind_of Hash, result_location
+    assert_include result_location, 'results'
+
+    result_latlng =  api.get_finest_latlng(result_location['results'])
+    assert_not_nil result_latlng
+    assert_instance_of Array, result_latlng
   end
 
   def test_api_xml_set
     opts = {address: 'Tour Eiffel, Paris, IDF, France', output: 'xml'}
     api = GmapsGeocoding::Api.new(opts)
-    result = api.get_location
     assert_not_nil api
-    assert_not_nil result
-    assert_equal 4, api.config.options.length
+
+    result_location = api.get_location
+    assert_not_nil result_location
+    assert_kind_of Hash, result_location
+    assert_include result_location, 'result'
+
+    result_latlng =  api.get_finest_latlng(result_location['result'])
+    assert_not_nil result_latlng
+    assert_instance_of Array, result_latlng
   end
 end

data/test/test_helper.rb

@@ -0,0 +1,6 @@
+require 'simplecov'
+
+SimpleCov.start do
+  add_filter 'test'
+end
+SimpleCov.command_name 'Unit Tests'

metadata

@@ -1,20 +1,18 @@
 --- !ruby/object:Gem::Specification
 name: gmaps_geocoding
 version: !ruby/object:Gem::Version
-  version: 0.0.4
-  prerelease: 
+  version: 0.1.0
 platform: ruby
 authors:
 - Christian Kakesa
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-04-17 00:00:00.000000000 Z
+date: 2013-07-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rest-client
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
@@ -22,7 +20,6 @@ dependencies:
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
@@ -30,7 +27,6 @@ dependencies:
 - !ruby/object:Gem::Dependency
   name: yajl-ruby
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
@@ -38,7 +34,6 @@ dependencies:
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
@@ -46,68 +41,74 @@ dependencies:
 - !ruby/object:Gem::Dependency
   name: nori
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: 2.0.4
+        version: 2.2.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: 2.0.4
+        version: 2.2.0
 - !ruby/object:Gem::Dependency
   name: nokogiri
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - ~>
       - !ruby/object:Gem::Version
-        version: 1.4.0
+        version: 1.6.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - ~>
       - !ruby/object:Gem::Version
-        version: 1.4.0
+        version: 1.6.0
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: '1.3'
+        version: 1.3.5
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: '1.3'
+        version: 1.3.5
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - '>='
       - !ruby/object:Gem::Version
         version: '0'
-description: ! "\n    A simple Ruby gem for Google Maps Geocoding API.\n    This gem
+description: "\n    A simple Ruby gem for Google Maps Geocoding API.\n    This gem
   return a Ruby Hash object of the result.\n  "
 email:
 - christian.kakesa@gmail.com
@@ -119,6 +120,7 @@ files:
 - .ruby-version
 - .travis.yml
 - .versions.conf
+- .yardopts
 - Gemfile
 - LICENSE.txt
 - README.md
@@ -129,36 +131,32 @@ files:
 - lib/gmaps_geocoding/config.rb
 - lib/gmaps_geocoding/version.rb
 - test/gmaps_geocoding_test.rb
+- test/test_helper.rb
 homepage: https://github.com/fenicks/gmaps_geocoding
 licenses:
 - MIT
+metadata: {}
 post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
-  none: false
   requirements:
-  - - ! '>='
+  - - '>='
     - !ruby/object:Gem::Version
       version: '0'
-      segments:
-      - 0
-      hash: 2934266397705908237
 required_rubygems_version: !ruby/object:Gem::Requirement
-  none: false
   requirements:
-  - - ! '>='
+  - - '>='
     - !ruby/object:Gem::Version
       version: '0'
-      segments:
-      - 0
-      hash: 2934266397705908237
 requirements: []
 rubyforge_project: 
-rubygems_version: 1.8.25
+rubygems_version: 2.0.3
 signing_key: 
-specification_version: 3
+specification_version: 4
 summary: Use Google Geocoding API from Ruby.
 test_files:
 - test/gmaps_geocoding_test.rb
+- test/test_helper.rb
+has_rdoc: