geo_rb 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: '028b35e41da078d2419f0b7a9400fbd98c84c5d06c021ad9c0d8eb5b642b321a'
+  data.tar.gz: 5cefbfc862f9b3063e879e7427a41c51913330ddc73294d9299940fbe5f6ac24
+SHA512:
+  metadata.gz: 739a39e6937c42157b810f34fd32bf93c56c16db5a2e6e6359e7ed68b3469113353f007b21f70c06265132f7c79594ae1628bf51c60563980357c32460507e59
+  data.tar.gz: 6064574fdfac9cd8c2638a467e13a181d7c6fd03222d96048f4264c2a39fca01d2bb3d812c0fb9b0a63c5e231976364e561be8a04a008dc6cc30af8ceb6a2388

data/.gitignore

@@ -0,0 +1,22 @@
+.DS_Store
+.idea
+.ruby-version
+.tool-versions
+gemfiles/*.lock
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/.rspec

@@ -0,0 +1 @@
+--require spec_helper --color

data/CHANGELOG.md

@@ -0,0 +1,3 @@
+# 0.0.1 (April 15, 2021)
+
+- Initial commit

data/Gemfile

@@ -0,0 +1,3 @@
+source "https://rubygems.org"
+
+gemspec

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2021 Victor Rodriguez
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,22 @@
+# geo_rb
+
+[![Gem Version](http://img.shields.io/gem/v/geo_rb.svg)][gem]
+[![Code Climate](https://codeclimate.com/github/kucho/geo_rb.svg)][codeclimate]
+
+geo_rb makes it easy for Ruby developers to locate the coordinates of addresses, cities, countries, and landmarks across the globe using third-party geocoders.
+
+It is heavily inspired by [geopy](https://github.com/geopy/geopy).
+
+## Install
+
+    gem install geo_rb
+
+## Usage
+
+### Address lookup
+```ruby
+plaza = GeoRb::Location.lookup("Plaza San Martin, Lima, Peru")
+palacio = GeoRb::Location.lookup("Palacio de Justicia, Lima, Peru")
+plaza.distance_to(palacio).km # => 0.6649563608870949
+palacio.distance_to(plaza).km # => 0.6649563608870949
+```

data/geo_rb.gemspec

@@ -0,0 +1,30 @@
+lib = File.expand_path("../lib", __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "geo_rb/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "geo_rb"
+  spec.required_ruby_version = ">= 2.4.0"
+  spec.homepage = "https://github.com/kucho/geo_rb"
+  spec.version = GeoRb::VERSION
+  spec.platform = Gem::Platform::RUBY
+  spec.summary = "Client for geolocation services"
+  spec.description = "geo_rb makes it easy for Ruby developers to locate the coordinates of addresses, cities, countries, and landmarks across the globe using third-party geocoders and other data sources"
+  spec.authors = ["Victor Rodriguez"]
+  spec.email = "victor.rodriguez.guriz@gmail.com"
+  spec.license = "MIT"
+
+  spec.files = `git ls-files`.split($/)
+  spec.test_files = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+  spec.metadata = {
+    "source_code_uri" => "https://github.com/kucho/geo_rb",
+    "changelog_uri" => "https://github.com/kucho/geo_rb/blob/master/CHANGELOG.md"
+  }
+
+  spec.add_runtime_dependency("geographiclib", "~> 0.0.2")
+
+  spec.add_development_dependency("bundler", "~> 2.2")
+  spec.add_development_dependency("standardrb", "~> 1.0")
+  spec.add_development_dependency("rspec", "~> 3.10")
+end

data/lib/geo_rb.rb

@@ -0,0 +1,16 @@
+require "logger"
+
+module GeoRb
+  autoload :Distance, "geo_rb/distance"
+  autoload :GeoCoders, "geo_rb/geo_coders"
+  autoload :Location, "geo_rb/location"
+  autoload :Point, "geo_rb/point"
+
+  def self.logger
+    @@logger ||= defined?(Rails) ? Rails.logger : Logger.new($stdout)
+  end
+
+  def self.logger=(logger)
+    @@logger = logger
+  end
+end

data/lib/geo_rb/distance.rb

@@ -0,0 +1,73 @@
+require "geographiclib"
+
+module GeoRb
+  class Distance
+    EARTH_RADIUS = 6_371.0088
+
+    attr_reader :kilometers
+    alias_method :km, :kilometers
+
+    def initialize(*locations)
+      @kilometers = case locations.size
+      when 1
+        Float(locations.first) if locations.size == 1
+      else
+        locations.each_cons(2).reduce(0) do |distance, pair|
+          a, b = sanitize_location(pair.first), sanitize_location(pair.last)
+          distance + measure(a, b)
+        end
+      end
+    end
+
+    def ensure_same_altitude(a, b)
+      raise LatitudeMismatch if (a.altitude - b.altitude).abs > 1e-6
+    end
+
+    def measure(a, b)
+      ensure_same_altitude(a, b)
+      r = GeographicLib::Geodesic::WGS84.inverse(a.latitude, a.longitude, b.latitude, b.longitude)
+      r[:s12] / 1_000
+    end
+
+    private
+
+    def sanitize_location(location)
+      case location
+      when Location, Point
+        location
+      when Array
+        case location.size
+        when 2..3
+          Point.new(*location.map(&:to_f))
+        else
+          raise CoordsError
+        end
+      when String
+        points = location.split(",")
+        raise CoordsError unless [2, 3].include?(points.size)
+
+        Point.new(*points.map(&:to_f))
+      else
+        raise LocationError
+      end
+    end
+  end
+
+  class LatitudeMismatch < ArgumentError
+    def message
+      "Calculating distance between points with different altitudes is not supported"
+    end
+  end
+
+  class LocationError < ArgumentError
+    def message
+      "Invalid locations"
+    end
+  end
+
+  class CoordsError < ArgumentError
+    def message
+      "In order to calculate the distance between points it is necessary to have at least latitude and longitude"
+    end
+  end
+end

data/lib/geo_rb/geo_coders.rb

@@ -0,0 +1,6 @@
+module GeoRb
+  module GeoCoders
+    autoload :Base, "geo_rb/geo_coders/base"
+    autoload :Nominatim, "geo_rb/geo_coders/nominatim"
+  end
+end

data/lib/geo_rb/geo_coders/base.rb

@@ -0,0 +1,28 @@
+require "json"
+require "net/http"
+
+module GeoRb
+  module GeoCoders
+    class Base
+      def call(url, post_process_proc = nil)
+        GeoRb.logger.debug data = parse_payload(fetch_data(URI(url)))
+        post_process_proc ? post_process_proc.call(data) : data
+      end
+
+      private
+
+      def fetch_data(url)
+        response = Net::HTTP.get(url)
+        JSON.parse(response).map { |result| result.transform_keys(&:to_sym) }
+      end
+
+      def format_bounding_box(a, b)
+        lat1 = [a.latitude, b.latitude].min
+        lon1 = [a.longitude, b.longitude].min
+        lat2 = [a.longitude, b.latitude].max
+        lon2 = [a.longitude, b.longitude].max
+        [lat1, lon1, lat2, lon2].join(",")
+      end
+    end
+  end
+end

data/lib/geo_rb/geo_coders/nominatim.rb

@@ -0,0 +1,85 @@
+module GeoRb
+  module GeoCoders
+    class Nominatim < Base
+      DEFAULT_NOMINATIM_DOMAIN = "https://nominatim.openstreetmap.org".freeze
+      API_PATHS = {
+        search: "/search",
+        reverse: "/reverse"
+      }.freeze
+      STRUCTURED_QUERY_PARAMS = %w[street city county state country postalcode].freeze
+
+      # @param [String | Hash] query: query can be a string or a hash for a structured query
+      #                               whose keys are one of: `street`, `city`, `county`, `state`,
+      #                               `country`, `postalcode`. For more information, see Nominatim's
+      #                               documentation for `structured requests`:
+      #                               https://nominatim.org/release-docs/develop/api/Search
+      # @param [Boolean] detailed: Include a breakdown of the address into elements
+      # @param [Boolean] exactly_one: Return one result or a list of results, if available.
+      #
+      # @param [ nil | Integer] limit: Maximum amount of results to return from Nominatim.
+      #                         Unless exactly_one is set to False, limit will always be 1.
+      #
+      # @param [Array] country_codes: Limit search results to a specific country (or a list of countries).
+      #                               A country_code should be the ISO 3166-1alpha2 code,
+      #                               e.g. ``gb`` for the United Kingdom, ``de`` for Germany, etc.
+      #
+      # @param [ nil | Array] viewbox: refer this area to find search results. Requires an array of Pointer.
+      #                                By default this is treated as a hint, if you want to restrict results
+      #                                to this area, specify ``bounded=True`` as well.
+      # @param [Boolean] bounded: Restrict the results to only items contained within the bounding ``viewbox``.
+      def geocode(query, detailed: false, language: nil, country_codes: [], viewbox: nil, exactly_one: true, limit: nil, bounded: false)
+        params = case query
+          when Hash
+            query.slice(STRUCTURED_QUERY_PARAMS)
+          else
+            {'q': query}
+        end
+
+        if exactly_one
+          params[:limit] = 1
+        elsif limit.nil?
+          raise "Limit cannot be less than 1" if limit < 1
+          params[:limit] = limit
+        end
+
+        params[:bounded] = 1 if bounded
+        params[:addressdetails] = 1 if detailed
+        params[:countrycodes] = country_codes.join(",") unless country_codes.empty?
+        params[:format] = "json"
+        params[:"accept-language"] = language if language
+        params[:viewbox] = format_bounding_box(viewbox[0], viewbox[1]) if viewbox
+
+        url = build_url(:search, params)
+        GeoRb.logger.debug url
+        proc = ->(data) { data.first } if exactly_one
+        call(url, proc)
+      end
+
+      private
+
+      def parse_payload(data)
+        data.map do |result|
+          result[:latitude] = Float(result.delete(:lat))
+          result[:longitude] = Float(result.delete(:lon))
+
+          params = {
+            address: result[:display_name],
+            raw: result,
+            point: Point.new(result[:latitude], result[:longitude])
+          }.compact
+
+          Location.new(**params)
+        end
+      end
+
+      def api(path)
+        DEFAULT_NOMINATIM_DOMAIN + API_PATHS[path]
+      end
+
+      def build_url(path, params)
+        params = URI.encode_www_form(params.to_a)
+        "#{api(path)}?#{params}"
+      end
+    end
+  end
+end

data/lib/geo_rb/location.rb

@@ -0,0 +1,32 @@
+require "forwardable"
+
+module GeoRb
+  # Contains a parsed geocoder response. Can be iterated over as
+  # ``(location<String>, (latitude<float>, longitude<Float))``.
+  #  Or one can access the properties ``address``, ``latitude``,
+  #  ``longitude``, or ``raw``. The last
+  #  is a dictionary of the geocoder's response for this item.
+  class Location
+    extend Forwardable
+    def_delegators :point, :latitude, :longitude, :altitude
+    attr_reader :address, :point, :raw
+
+    def self.lookup(text, adapter: GeoRb::GeoCoders::Nominatim, **options)
+      adapter.new.geocode(text, **options)
+    end
+
+    def initialize(address:, raw:, point: Point)
+      @address = address
+      @point = point
+      @raw = raw
+    end
+
+    def distance_to(location)
+      Distance.new(self, location)
+    end
+
+    def to_h
+      {address: address}.merge(point.to_h)
+    end
+  end
+end

data/lib/geo_rb/point.rb

@@ -0,0 +1,42 @@
+module GeoRb
+  class Point
+    attr_reader :latitude, :longitude, :altitude
+
+    def initialize(latitude = 0.0, longitude = 0.0, altitude = 0.0)
+      @latitude, @longitude, @altitude = normalize_coordinates(latitude, longitude, altitude)
+    end
+
+    def to_h
+      instance_variables.map do |var|
+        [var[1..].to_sym, instance_variable_get(var)]
+      end.to_h
+    end
+
+    private
+
+    # Normalize angle `x` to be within `[-limit; limit)` range.
+    def normalize_angle(x, limit)
+      double_limit = limit * 2.0
+      modulo = x % double_limit
+      return modulo + double_limit if modulo < -limit
+      return modulo - double_limit if modulo >= limit
+
+      modulo
+    end
+
+    def normalize_coordinates(latitude, longitude, altitude)
+      latitude = Float(latitude)
+      longitude = Float(longitude)
+      altitude = Float(altitude)
+
+      unless [latitude, longitude, altitude].all?(&:finite?)
+        raise "Point coordinates must be finite. #{latitude}, #{longitude} #{altitude} has been passed as coordinates."
+      end
+
+      raise "Latitude must be in the [-90; 90] range." if latitude.abs > 90
+
+      longitude = normalize_angle(longitude, 180.0) if longitude.abs > 180
+      [latitude, longitude, altitude]
+    end
+  end
+end

data/lib/geo_rb/version.rb

@@ -0,0 +1,3 @@
+module GeoRb
+  VERSION = Gem::Version.new("0.0.1")
+end

data/spec/geo_rb/distance_spec.rb

@@ -0,0 +1,34 @@
+describe GeoRb::Distance do
+  subject { described_class.new(*locations).km }
+  let(:north_pole) { GeoRb::Point.new(90, 0) }
+  let(:south_pole) { GeoRb::Point.new(-90, 0) }
+  let(:earth_radius) { described_class::EARTH_RADIUS }
+  let(:earth_circumference) { 2 * Math::PI * earth_radius }
+
+  describe "#measure" do
+    context "when points are the same" do
+      let(:locations) { %w[0,0 0,0] }
+
+      it { is_expected.to eq 0 }
+    end
+
+    context "when distinct points" do
+      let(:locations) { %w[0,0 0,1] }
+
+      it { is_expected.to_not eq 0 }
+    end
+
+    context "when across antimeridian" do
+      let(:nines) { 1 - 1e-30 } # 0.(9)
+      let(:locations) { [[0, -179 - nines], [0, 179 + nines]] }
+
+      it { is_expected.to eq 0 }
+    end
+
+    context "when trip between poles" do
+      let(:locations) { [north_pole, south_pole] }
+
+      it { should be_within(12).of(earth_circumference / 2) }
+    end
+  end
+end

data/spec/geo_rb/geo_coders/nominatim_spec.rb

@@ -0,0 +1,55 @@
+describe GeoRb::GeoCoders::Nominatim do
+  subject { client.geocode(query, **optional_params).to_h }
+  let(:raw_response) { client.geocode(query, **optional_params).raw }
+  let(:optional_params) { {} }
+  let(:client) { described_class.new }
+
+  describe "#geocode" do
+    describe "only query" do
+      context "with no optional params" do
+        let(:query) { "435 north michigan ave, chicago il 60611 usa" }
+        let(:expected_result) { {latitude: 41.89037385, longitude: -87.62367299422614, altitude: 0} }
+
+        it { is_expected.to include(expected_result) }
+      end
+
+      context "when query is CJK" do
+        let(:query) { "故宫 北京" }
+        let(:expected_result) { {latitude: 39.91727565, longitude: 116.39076940577283, altitude: 0} }
+
+        it { is_expected.to include(expected_result) }
+      end
+    end
+
+    describe "with viewbox" do
+      let(:points) do
+        [
+          GeoRb::Point.new(56.588456, 84.719353),
+          GeoRb::Point.new(56.437293, 85.296822)
+        ]
+      end
+      let(:query) { "строитель томск" }
+
+      context "when not bounded" do
+        let(:optional_params) { {viewbox: points} }
+        let(:expected_result) { {latitude: 56.4129459, longitude: 84.84783106981399} }
+
+        it { is_expected.to include(expected_result) }
+      end
+
+      context "when bounded" do
+        let(:optional_params) { {viewbox: points, bounded: true} }
+
+        it { is_expected.to eq({}) }
+      end
+    end
+
+    describe "with language" do
+      let(:query) { "Mohrenstrasse Berlin" }
+      let(:optional_params) { {language: "es", detailed: true} }
+      let(:expected_result) { {"country" => "Alemania"} }
+
+      it { expect(raw_response[:address]).to include(expected_result) }
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,8 @@
+require "rspec"
+require "geo_rb"
+
+RSpec.configure do |config|
+  config.expect_with :rspec do |c|
+    c.syntax = :expect # disables `should`
+  end
+end

metadata

@@ -0,0 +1,123 @@
+--- !ruby/object:Gem::Specification
+name: geo_rb
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Victor Rodriguez
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2021-04-15 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: geographiclib
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.0.2
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.0.2
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.2'
+- !ruby/object:Gem::Dependency
+  name: standardrb
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.10'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.10'
+description: geo_rb makes it easy for Ruby developers to locate the coordinates of
+  addresses, cities, countries, and landmarks across the globe using third-party geocoders
+  and other data sources
+email: victor.rodriguez.guriz@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- CHANGELOG.md
+- Gemfile
+- LICENSE
+- README.md
+- geo_rb.gemspec
+- lib/geo_rb.rb
+- lib/geo_rb/distance.rb
+- lib/geo_rb/geo_coders.rb
+- lib/geo_rb/geo_coders/base.rb
+- lib/geo_rb/geo_coders/nominatim.rb
+- lib/geo_rb/location.rb
+- lib/geo_rb/point.rb
+- lib/geo_rb/version.rb
+- spec/geo_rb/distance_spec.rb
+- spec/geo_rb/geo_coders/nominatim_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/kucho/geo_rb
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/kucho/geo_rb
+  changelog_uri: https://github.com/kucho/geo_rb/blob/master/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.4.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.2.3
+signing_key:
+specification_version: 4
+summary: Client for geolocation services
+test_files:
+- spec/geo_rb/distance_spec.rb
+- spec/geo_rb/geo_coders/nominatim_spec.rb
+- spec/spec_helper.rb