Structured search requests

README.md

@@ -34,6 +34,29 @@ end
 puts "Found #{places.count} places."
 ```
 
+### Structured requests
+
+```ruby
+places = Nominatim.search.city('San Antonio').country('Mexico').limit(10).address_details(true)
+
+for place in places
+  puts "#{place.display_name} (#{place.type})"
+end
+
+puts "Found #{places.count} places."
+```
+
+Nominatim::Search has the following methods to craft structures requests:
+
+- street: accepts house number and street name as parameters
+- city
+- county
+- state
+- country
+- postalcode
+
+See http://wiki.openstreetmap.org/wiki/Nominatim#Parameters
+
 ## Configuration
 
 ```ruby

lib/nominatim/search.rb

@@ -9,10 +9,28 @@ def initialize
 
     # Iterates over the search results.
     def each(&block)
+      @criteria.delete(:q) if (@criteria.keys & [:street, :city, :county, :state, :country, :postalcode]).count > 0
       @results ||= get(Nominatim.config.search_url, @criteria).body.map! { |attrs| Nominatim::Place.new(attrs) }
       @results.each(&block)
     end
 
+    # Structured search requests
+    # @see https://wiki.openstreetmap.org/wiki/Nominatim
+    %w(city county state country postalcode).to_a.each do |criterion|
+      define_method(criterion) do |param|
+        @criteria[criterion.to_sym] = param
+        self
+      end
+    end
+
+    # Structured street search request
+    #
+    # @see https://wiki.openstreetmap.org/wiki/Nominatim
+    def street housenumber, streetname
+      @criteria[:street] = "#{housenumber} #{streetname}"
+      self
+    end
+
     # Query string to search for.
     #
     # @param q [String] Query string

spec/nominatim/search_spec.rb

@@ -18,10 +18,15 @@
 
     let(:search) { Nominatim::Search.new.query('Los Angeles').limit(1) }
 
+    let(:structured_search){ Nominatim::Search.new.query('Text').city('Los Angeles').country('us').limit(1) }
+
     before do
       stub_get('/search').
         with(query: { q: 'Los Angeles', limit: 1 }).
         to_return(body: fixture('search.json'))
+      stub_get('/search').
+        with(query: { city: 'Los Angeles', country: 'us', limit: 1 }).
+        to_return(body: fixture('search.json'))
     end
 
     it 'iterates over the matching places' do
@@ -39,6 +44,12 @@
       search.first.lat.should eq 34.0966764
       search.first.lon.should eq -117.7196785
     end
+
+    it 'omits q parameter from structured search' do
+      structured_search.first.display_name.should eq 'Los Angeles, California, United States of America'
+      structured_search.first.lat.should eq 34.0966764
+      structured_search.first.lon.should eq -117.7196785
+    end
   end
 
   describe '#query' do
@@ -67,6 +78,40 @@
     end
   end
 
+  describe '#street' do
+    it 'adds a street criterion' do
+      search.street('1000', 'street name')
+      search.criteria[:street].should eq "1000 street name"
+    end
+  end
+  describe '#city' do
+    it 'adds a city criterion' do
+      search.city('City name')
+      search.criteria[:city].should eq "City name"
+    end
+  end
+  describe '#county' do
+    it 'adds a county criterion' do
+      search.county('County name')
+      search.criteria[:county].should eq "County name"
+    end
+  end
+
+  describe '#state' do
+    it 'adds a state criterion' do
+      search.state('State name')
+      search.criteria[:state].should eq "State name"
+    end
+  end
+
+  describe '#country' do
+    it 'adds a country criterion' do
+      search.country('Country name')
+      search.criteria[:country].should eq "Country name"
+    end
+  end
+
+
   describe '#bounded' do
     it 'adds a bounded criterion' do
       search.bounded(true)