nominatim 0.0.1

data/.gitignore

@@ -0,0 +1,18 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+coverage

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--format progress

data/.travis.yml

@@ -0,0 +1,7 @@
+language: ruby
+rvm:
+  - 1.9.3
+  - 1.9.2
+  - jruby
+  - rbx
+script: "bundle exec rake"

data/CHANGELOG.md

@@ -0,0 +1,3 @@
+## v0.0.1
+
+* Initial release.

data/Gemfile

@@ -0,0 +1,8 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in nominatim.gemspec
+gemspec
+
+gem 'guard'
+gem 'guard-rspec'
+gem 'guard-bundler'

data/Guardfile

@@ -0,0 +1,13 @@
+# A sample Guardfile
+# More info at https://github.com/guard/guard#readme
+
+guard 'bundler' do
+  watch('Gemfile')
+  watch(/^.+\.gemspec/)
+end
+
+guard 'rspec', :version => 2 do
+  watch(%r{^spec/.+_spec\.rb$})
+  watch(%r{^lib/(.+)\.rb$})     { |m| "spec/#{m[1]}_spec.rb" }
+  watch('spec/spec_helper.rb')  { "spec" }
+end

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Jakub Svehla
+
+MIT License
+
+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,45 @@
+# Nominatim
+
+A Ruby wrapper for the Nominatim API.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'nominatim'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install nominatim
+
+## Usage
+
+```ruby
+places = Nominatim.search('San Francisco').limit(10).address_details(true)
+
+for place in places
+  puts "#{place.display_name} (#{place.type})"
+end
+puts "Found #{places.count} places."
+```
+
+## Configuration
+
+```ruby
+Nominatim.configure do |config|
+  config.email = 'your-email-address@gmail.com'
+  config.endpoint = 'http://nominatim.openstreetmap.org'
+end
+```
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Added some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1,11 @@
+#!/usr/bin/env rake
+require "bundler/gem_tasks"
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new
+
+task :test => :spec
+task :default => :spec
+
+require 'yard'
+YARD::Rake::YardocTask.new

data/lib/nominatim.rb

@@ -0,0 +1,26 @@
+require "nominatim/version"
+require "nominatim/configuration"
+require "nominatim/address"
+require "nominatim/place"
+require "nominatim/response/parse_json"
+require "nominatim/client"
+require "nominatim/search"
+
+module Nominatim
+
+  # @return [Nominatim::Search]
+  def self.search(q = nil)
+    search = Nominatim::Search.new
+    search.query(q) if q
+    search
+  end
+
+  # @return [Nominatim::Configuration]
+  def self.config
+    @config ||= Configuration.new
+  end
+
+  def self.configure(&block)
+    config.configure &block
+  end
+end

data/lib/nominatim/address.rb

@@ -0,0 +1,75 @@
+module Nominatim
+  class Address
+    def initialize(attrs = {})
+      @attrs = attrs
+    end
+
+    def attraction
+      @attraction ||= @attrs[:attraction]
+    end
+
+    def clothes
+      @clothes ||= @attrs[:clothes]
+    end
+
+    def house_number
+      @house_number ||= @attrs[:house_number]
+    end
+
+    def road
+      @road ||= @attrs[:road]
+    end
+
+    def commercial
+      @commercial ||= @attrs[:commercial]
+    end
+
+    def pedestrian
+      @pedestrian ||= @attrs[:pedestrian]
+    end
+
+    def suburb
+      @suburb ||= @attrs[:suburb]
+    end
+
+    def city_district
+      @city_district ||= @attrs[:city_district]
+    end
+
+    def city
+      @city ||= @attrs[:city]
+    end
+
+    def administrative
+      @administrative ||= @attrs[:administrative]
+    end
+
+    def county
+      @county ||= @attrs[:county]
+    end
+
+    def state_district
+      @state_district ||= @attrs[:state_district]
+    end
+
+    def state
+      @state ||= @attrs[:state]
+    end
+
+    def postcode
+      @postcode ||= @attrs[:postcode]
+    end
+
+    def country
+      @country ||= @attrs[:country]
+    end
+
+    def country_code
+      @country_code ||= @attrs[:country_code]
+    end
+
+    def place
+      @place ||= @attrs[:place]
+    end
+  end
+end

data/lib/nominatim/client.rb

@@ -0,0 +1,32 @@
+require 'faraday'
+
+module Nominatim
+  class Client
+
+    # Performs an HTTP GET request
+    def get(path, params = {})
+      connection.get path, params
+    end
+
+    private
+
+    # Returns a Faraday::Connection object
+    #
+    # @return [Faraday::Connection]
+    def connection
+      return @connection if defined? @connection
+
+      @connection = Faraday.new Nominatim.config.endpoint do |builder|
+        builder.use Nominatim::Response::ParseJson
+        builder.adapter Faraday.default_adapter
+      end
+
+      @connection.params[:format] = 'json'
+      @connection.params[:email] = Nominatim.config.email if Nominatim.config.email
+
+      @connection.headers[:user_agent] = Nominatim.config.user_agent
+
+      @connection
+    end
+  end
+end

data/lib/nominatim/configuration.rb

@@ -0,0 +1,33 @@
+module Nominatim
+  class Configuration
+
+    DEFAULT_ENDPOINT = 'http://nominatim.openstreetmap.org'
+
+    DEFAULT_USER_AGENT = "Nominatim Ruby Gem #{Nominatim::VERSION}"
+
+    DEFAULT_EMAIL = nil
+
+    VALID_OPTIONS_KEYS = [
+      :endpoint,
+      :user_agent,
+      :email
+    ]
+
+    attr_accessor *VALID_OPTIONS_KEYS
+
+    def initialize
+      reset!
+    end
+
+    def configure
+      yield self
+      self
+    end
+
+    def reset!
+      self.endpoint   = DEFAULT_ENDPOINT
+      self.user_agent = DEFAULT_USER_AGENT
+      self.email      = DEFAULT_EMAIL
+    end
+  end
+end

data/lib/nominatim/place.rb

@@ -0,0 +1,57 @@
+module Nominatim
+  class Place
+    # attr_reader :attrs
+    # alias to_hash attrs
+
+    def initialize(attrs = {})
+      @attrs = attrs
+    end
+
+    def display_name
+      @display_name ||= @attrs[:display_name]
+    end
+
+    def class
+      @class ||= @attrs[:class]
+    end
+
+    def type
+      @type ||= @attrs[:type]
+    end
+
+    def address
+      @address ||= Nominatim::Address.new(@attrs[:address]) unless @attrs[:address].nil?
+    end
+
+    def lat
+      @lat ||= @attrs[:lat] || @attrs[:latitude]
+    end
+    alias latitude lat
+
+    def lon
+      @lon ||= @attrs[:lon] || @attrs[:longitude]
+    end
+    alias longitude lon
+
+    def boundingbox
+      @boundingbox ||= @attrs[:boundingbox]
+    end
+    alias bounding_box boundingbox
+
+    def polygonpoints
+      @polygonpoints ||= @attrs[:polygonpoints]
+    end
+
+    def place_id
+      @place_id ||= @attrs[:place_id]
+    end
+
+    def osm_id
+      @osm_id ||= @attrs[:osm_id]
+    end
+
+    def osm_type
+      @osm_type ||= @attrs[:osm_type]
+    end
+  end
+end

data/lib/nominatim/response/parse_json.rb

@@ -0,0 +1,16 @@
+require 'faraday'
+require 'multi_json'
+
+module Nominatim
+  module Response
+    class ParseJson < Faraday::Response::Middleware
+      def on_complete(env)
+        if env[:body].empty?
+          env[:body] = nil
+        else
+          env[:body] = MultiJson.load(env[:body], symbolize_keys: true)
+        end
+      end
+    end
+  end
+end

data/lib/nominatim/search.rb

@@ -0,0 +1,98 @@
+module Nominatim
+  class Search < Client
+    include Enumerable
+    attr_reader :criteria
+
+    def initialize
+      @criteria = {}
+    end
+
+    # Iterates over the search results.
+    def each(&block)
+      get('/search', @criteria).body.map! { |attrs| Nominatim::Place.new(attrs) }.each(&block)
+    end
+
+    # Query string to search from.
+    #
+    # @param q [String] Query string
+    # @return [Nominatim::Search]
+    def query(q)
+      @criteria[:q] = q
+      self
+    end
+
+    # Limit search results to a specific country (or a list of countries).
+    #
+    # @param codes [Array<String>, String]
+    # @see https://wiki.openstreetmap.org/wiki/Nominatim
+    # @return [Nominatim::Search]
+    def country_codes(codes)
+      if codes.instance_of? Array
+        @criteria[:countrycodes] = codes.join(',')
+      else
+        @criteria[:countrycodes] = codes
+      end
+      self
+    end
+
+    # The preferred area to find search results.
+    #
+    # @param viewbox [Array<String>]
+    # @return [Nominatim::Search]
+    def viewbox(viewbox)
+      @criteria[:viewbox] = viewbox.join(',')
+      self
+    end
+
+    # Restrict the results to only items contained with the bounding box.
+    #
+    # @param bool [true, false]
+    # @see https://wiki.openstreetmap.org/wiki/Nominatim
+    # @return [Nominatim::Search]
+    def bounded(bool)
+      @criteria[:bounded] = bool ? 1 : 0
+      self
+    end
+
+    # Output polygon outlines for items found.
+    #
+    # @param bool [true, false]
+    # @return [Nominatim::Search]
+    def polygon(bool)
+      @criteria[:polygon] = bool ? 1 : 0
+      self
+    end
+
+    # Include a breakdown of the address into elements.
+    #
+    # @param bool [true, false]
+    # @return [Nominatim::Search]
+    def address_details(bool)
+      @criteria[:addressdetails] = bool ? 1 : 0
+      self
+    end
+
+    # Exclude given place ids from the search result.
+    #
+    # @param ids [Array<String>, String] Place ids
+    # @return [Nominatim::Search]
+    def exclude_place_ids(ids)
+      if ids.instance_of? Array
+        @criteria[:exclude_place_ids] = ids.join(',')
+      else
+        @criteria[:exclude_place_ids] = ids
+      end
+      self
+    end
+
+    # Limit the number of returned results.
+    #
+    # @param limit [Integer]
+    # @return [Nominatim::Search]
+    def limit(limit)
+      @criteria[:limit] = limit
+      self
+    end
+
+  end
+end