underpass 0.0.7 → 0.9.0

data/lib/underpass/filter.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Underpass
+  # Post-query filtering of {Feature} objects by tag properties.
+  #
+  # @example Filter restaurants by cuisine
+  #   filter = Underpass::Filter.new(features)
+  #   italian = filter.where(cuisine: 'italian')
+  class Filter
+    # Creates a new filter for the given features.
+    #
+    # @param features [Array<Feature>] the features to filter
+    def initialize(features)
+      @features = features
+    end
+
+    # Returns features whose properties match all given conditions.
+    #
+    # Conditions can be exact values, regular expressions, or arrays of values.
+    #
+    # @param conditions [Hash{Symbol => String, Regexp, Array}] tag conditions to match
+    # @return [Array<Feature>] features matching all conditions
+    #
+    # @example Exact match
+    #   filter.where(cuisine: 'italian')
+    # @example Regex match
+    #   filter.where(name: /pizza/i)
+    # @example Array inclusion
+    #   filter.where(cuisine: ['italian', 'mexican'])
+    def where(conditions = {})
+      @features.select do |feature|
+        conditions.all? { |key, value| match_condition?(feature.properties[key], value) }
+      end
+    end
+
+    # Returns features that do not match any of the given conditions.
+    #
+    # @param conditions [Hash{Symbol => String}] tag conditions to reject
+    # @return [Array<Feature>] features not matching any condition
+    def reject(conditions = {})
+      @features.reject do |feature|
+        conditions.any? { |key, value| feature.properties[key] == value.to_s }
+      end
+    end
+
+    private
+
+    def match_condition?(prop_value, condition)
+      case condition
+      when Regexp then prop_value&.match?(condition)
+      when Array then condition.include?(prop_value)
+      else prop_value == condition.to_s
+      end
+    end
+  end
+end

data/lib/underpass/geo_json.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require 'rgeo/geo_json'
+
+module Underpass
+  # Encodes {Feature} arrays as GeoJSON FeatureCollections.
+  #
+  # @example Export query results to GeoJSON
+  #   features = Underpass::QL::Query.perform(bbox, query)
+  #   geojson = Underpass::GeoJSON.encode(features)
+  module GeoJSON
+    # Encodes an array of features as a GeoJSON FeatureCollection hash.
+    #
+    # @param features [Array<Feature>] the features to encode
+    # @return [Hash] a GeoJSON FeatureCollection
+    def self.encode(features)
+      geo_features = features.map do |f|
+        RGeo::GeoJSON::Feature.new(f.geometry, f.id, f.properties)
+      end
+      RGeo::GeoJSON.encode(RGeo::GeoJSON::FeatureCollection.new(geo_features))
+    end
+  end
+end

data/lib/underpass/matcher.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module Underpass
+  # Extracts matching elements from an Overpass API response.
+  #
+  # A "match" is a response element that has a +tags+ key, indicating it is
+  # a tagged OSM element rather than a bare geometry node. Each match is
+  # converted into a {Feature} with the appropriate RGeo geometry.
+  class Matcher
+    # Creates a new matcher for the given response.
+    #
+    # @param response [QL::Response] a parsed API response
+    # @param requested_types [Array<String>, nil] element types to include
+    #   (e.g. +["node", "way"]+). Defaults to all types when +nil+.
+    def initialize(response, requested_types = nil)
+      @nodes     = response.nodes
+      @ways      = response.ways
+      @relations = response.relations
+      @requested_types = requested_types || %w[node way relation]
+    end
+
+    # Returns all matched features as an array.
+    #
+    # @return [Array<Feature>] the matched features
+    def matches
+      @matches ||= lazy_matches.to_a
+    end
+
+    # Returns a lazy enumerator of matched features.
+    #
+    # @return [Enumerator::Lazy<Feature>] lazy enumerator of features
+    def lazy_matches
+      tagged_elements.lazy.flat_map { |element| features_for(element) }
+    end
+
+    private
+
+    def tagged_elements
+      elements = []
+      elements.concat(@nodes.values.select { |n| n.key?(:tags) }) if @requested_types.include?('node')
+      elements.concat(@ways.values.select { |w| w.key?(:tags) }) if @requested_types.include?('way')
+      elements.concat(@relations.values.select { |r| r.key?(:tags) }) if @requested_types.include?('relation')
+      elements
+    end
+
+    def features_for(element)
+      case element[:type]
+      when 'node'
+        [build_feature(Shape.point_from_node(element), element)]
+      when 'way'
+        [build_feature(way_geometry(element), element)]
+      when 'relation'
+        relation_features(element)
+      else
+        []
+      end
+    end
+
+    def relation_features(relation)
+      geometry = relation_geometry(relation)
+      if geometry.is_a?(Array)
+        geometry.map { |g| build_feature(g, relation) }
+      else
+        [build_feature(geometry, relation)]
+      end
+    end
+
+    def relation_geometry(relation)
+      case relation[:tags][:type]
+      when 'multipolygon'
+        Shape.multipolygon_from_relation(relation, @ways, @nodes)
+      when 'route'
+        Shape.multi_line_string_from_relation(relation, @ways, @nodes)
+      else
+        expand_relation_members(relation)
+      end
+    end
+
+    def expand_relation_members(relation)
+      relation[:members].filter_map do |member|
+        case member[:type]
+        when 'node' then Shape.point_from_node(@nodes[member[:ref]])
+        when 'way' then way_geometry(@ways[member[:ref]])
+        end
+      end
+    end
+
+    def way_geometry(way)
+      if Shape.open_way?(way)
+        Shape.polygon_from_way(way, @nodes)
+      else
+        Shape.line_string_from_way(way, @nodes)
+      end
+    end
+
+    def build_feature(geometry, element)
+      Feature.new(
+        geometry: geometry,
+        properties: element[:tags] || {},
+        id: element[:id],
+        type: element[:type]
+      )
+    end
+  end
+end

data/lib/underpass/ql/bounding_box.rb

@@ -2,13 +2,26 @@
 
 module Underpass
   module QL
-    # Bounding box related utilities.
+    # Converts RGeo geometries and WKT strings into Overpass QL bounding box syntax.
     class BoundingBox
-      # Returns the Overpass query language bounding box string
-      # when provided with an RGeo geometry
-      def self.from_geometry(geometry)
-        r_bb = RGeo::Cartesian::BoundingBox.create_from_geometry(geometry)
-        "bbox:#{r_bb.min_y},#{r_bb.min_x},#{r_bb.max_y},#{r_bb.max_x}"
+      class << self
+        # Returns the Overpass QL bounding box string from a WKT string.
+        #
+        # @param wkt [String] a Well Known Text geometry string
+        # @return [String] an Overpass QL bounding box (e.g. +"bbox:47.65,23.669,47.674,23.725"+)
+        def from_wkt(wkt)
+          geometry = RGeo::Geographic.spherical_factory.parse_wkt(wkt)
+          from_geometry(geometry)
+        end
+
+        # Returns the Overpass QL bounding box string from an RGeo geometry.
+        #
+        # @param geometry [RGeo::Feature::Geometry] an RGeo geometry
+        # @return [String] an Overpass QL bounding box (e.g. +"bbox:47.65,23.669,47.674,23.725"+)
+        def from_geometry(geometry)
+          r_bb = RGeo::Cartesian::BoundingBox.create_from_geometry(geometry)
+          "bbox:#{r_bb.min_y},#{r_bb.min_x},#{r_bb.max_y},#{r_bb.max_x}"
+        end
       end
     end
   end

data/lib/underpass/ql/builder.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Underpass
+  module QL
+    # DSL for building Overpass QL queries programmatically.
+    #
+    # @example Query for restaurants
+    #   builder = Underpass::QL::Builder.new
+    #   builder.node('amenity' => 'restaurant')
+    #   Underpass::QL::Query.perform(bbox, builder)
+    #
+    # @example Proximity search with around
+    #   builder = Underpass::QL::Builder.new
+    #   builder.node('amenity' => 'cafe').around(500, 44.4268, 26.1025)
+    class Builder
+      # Creates a new empty builder.
+      def initialize
+        @statements = []
+        @around = nil
+      end
+
+      # Adds a node query statement.
+      #
+      # @param tags [Hash{String => String}] tag filters
+      # @return [self] for method chaining
+      def node(tags = {})
+        @statements << build_statement('node', tags)
+        self
+      end
+
+      # Adds a way query statement.
+      #
+      # @param tags [Hash{String => String}] tag filters
+      # @return [self] for method chaining
+      def way(tags = {})
+        @statements << build_statement('way', tags)
+        self
+      end
+
+      # Adds a relation query statement.
+      #
+      # @param tags [Hash{String => String}] tag filters
+      # @return [self] for method chaining
+      def relation(tags = {})
+        @statements << build_statement('relation', tags)
+        self
+      end
+
+      # Adds a node/way/relation (nwr) query statement.
+      #
+      # @param tags [Hash{String => String}] tag filters
+      # @return [self] for method chaining
+      def nwr(tags = {})
+        @statements << build_statement('nwr', tags)
+        self
+      end
+
+      # Sets a proximity filter for all statements.
+      #
+      # @param radius [Numeric] search radius in meters
+      # @param lat_or_point [Numeric, RGeo::Feature::Point] latitude or an RGeo point
+      # @param lon [Numeric, nil] longitude (required when +lat_or_point+ is numeric)
+      # @return [self] for method chaining
+      def around(radius, lat_or_point, lon = nil)
+        @around = if lat_or_point.respond_to?(:y)
+                    { radius: radius, lat: lat_or_point.y, lon: lat_or_point.x }
+                  else
+                    { radius: radius, lat: lat_or_point, lon: lon }
+                  end
+        self
+      end
+
+      # Converts the builder into an Overpass QL query string.
+      #
+      # @return [String] the Overpass QL query
+      def to_ql
+        if @around
+          @statements.map { |s| append_around(s) }.join("\n")
+        else
+          @statements.join("\n")
+        end
+      end
+
+      private
+
+      def build_statement(type, tags)
+        tag_filters = tags.map { |k, v| "[\"#{k}\"=\"#{v}\"]" }.join
+        "#{type}#{tag_filters};"
+      end
+
+      def append_around(statement)
+        around_filter = "(around:#{@around[:radius]},#{@around[:lat]},#{@around[:lon]})"
+        statement.sub(';', "#{around_filter};")
+      end
+    end
+  end
+end

data/lib/underpass/ql/query.rb

@@ -1,17 +1,63 @@
 # frozen_string_literal: true
 
 module Underpass
+  # Namespace for Overpass Query Language related classes.
   module QL
-    # Provides a shortcut method that makes it easy to work with the library
+    # High-level entry point for querying the Overpass API.
+    #
+    # Glues together {Request}, {Client}, {Response}, {QueryAnalyzer}, and
+    # {Matcher} to provide a single-call interface.
+    #
+    # @example Query with a bounding box
+    #   features = Underpass::QL::Query.perform(bbox, 'way["building"="yes"];')
+    #
+    # @example Query with a named area
+    #   features = Underpass::QL::Query.perform_in_area('Romania', 'node["place"="city"];')
     class Query
-      # Shortcut method that glues together the whole library.
-      # * +bounding_box+ an RGeo polygon
-      # * +query+ is the Overpass QL query
+      # Queries the Overpass API within a bounding box.
+      #
+      # @param bounding_box [RGeo::Feature::Geometry] an RGeo polygon defining the search area
+      # @param query [String, Builder] an Overpass QL query string or a {Builder} instance
+      # @return [Array<Feature>] the matched features
+      # @raise [RateLimitError] when rate limited after exhausting retries
+      # @raise [TimeoutError] when the API times out after exhausting retries
+      # @raise [ApiError] when the API returns an unexpected error
       def self.perform(bounding_box, query)
-        op_bbox = Underpass::QL::BoundingBox.from_geometry(bounding_box)
-        response = Underpass::QL::Request.new(query, op_bbox).run
-        Underpass::QL::Parser.new(response).parse.matches
+        query_string     = resolve_query(query)
+        op_bbox          = Underpass::QL::BoundingBox.from_geometry(bounding_box)
+        request          = Underpass::QL::Request.new(query_string, op_bbox)
+        execute(request, query_string)
       end
+
+      # Queries the Overpass API within a named area (e.g. "Romania").
+      #
+      # @param area_name [String] an OSM area name
+      # @param query [String, Builder] an Overpass QL query string or a {Builder} instance
+      # @return [Array<Feature>] the matched features
+      # @raise [RateLimitError] when rate limited after exhausting retries
+      # @raise [TimeoutError] when the API times out after exhausting retries
+      # @raise [ApiError] when the API returns an unexpected error
+      def self.perform_in_area(area_name, query)
+        query_string = resolve_query(query)
+        request      = Underpass::QL::Request.new(query_string, nil, area_name: area_name)
+        execute(request, query_string)
+      end
+
+      def self.resolve_query(query)
+        query.respond_to?(:to_ql) ? query.to_ql : query
+      end
+      private_class_method :resolve_query
+
+      def self.execute(request, query_string)
+        api_response     = Underpass::Client.perform(request)
+        response         = Underpass::QL::Response.new(api_response)
+        query_analyzer   = Underpass::QL::QueryAnalyzer.new(query_string)
+        requested_types  = query_analyzer.requested_types
+        matcher          = Underpass::Matcher.new(response, requested_types)
+
+        matcher.matches
+      end
+      private_class_method :execute
     end
   end
 end

data/lib/underpass/ql/query_analyzer.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Underpass
+  module QL
+    # Analyzes an Overpass QL query string to determine which element types
+    # (node, way, relation) are requested.
+    #
+    # Used internally by {Query} to pass type hints to {Matcher}.
+    class QueryAnalyzer
+      # @return [Array<String>] the recognized OSM element types
+      MATCH_TYPES = %w[node way relation].freeze
+
+      # Creates a new analyzer for the given query string.
+      #
+      # @param query [String, nil] an Overpass QL query string
+      def initialize(query)
+        @query = query
+      end
+
+      # Returns the element types requested in the query.
+      #
+      # Falls back to all types when the query is empty or contains
+      # no recognized type keywords.
+      #
+      # @return [Array<String>] requested types (e.g. +["node", "way"]+)
+      def requested_types
+        return MATCH_TYPES if empty_query?
+
+        types = parse_types_from_query
+        types.empty? ? MATCH_TYPES : types
+      end
+
+      private
+
+      def empty_query?
+        @query.nil? || @query.strip.empty?
+      end
+
+      def parse_types_from_query
+        lines = @query.strip.split(';').map(&:strip).reject(&:empty?)
+        lines.map { |line| first_word(line) }
+             .select { |word| MATCH_TYPES.include?(word) }
+             .uniq
+      end
+
+      def first_word(line)
+        line.split(/[\[\s]+/).first
+      end
+    end
+  end
+end

data/lib/underpass/ql/request.rb

@@ -2,34 +2,67 @@
 
 module Underpass
   module QL
-    # Deals with performing the Overpass API request
+    # Prepares the full Overpass QL query string from a user query,
+    # bounding box, and configuration options.
+    #
+    # Supports both bounding-box and named-area query templates.
     class Request
-      API_URI = 'https://overpass-api.de/api/interpreter'
+      # @api private
       QUERY_TEMPLATE = <<-TEMPLATE
-        [out:json][timeout:25]BBOX;
+        [out:json][timeout:TIMEOUT]BBOX;
         (
           QUERY
         );
         out body;
-        >;
+        RECURSE
         out skel qt;
       TEMPLATE
 
-      def initialize(query, bbox)
+      # @api private
+      AREA_QUERY_TEMPLATE = <<-TEMPLATE
+        [out:json][timeout:TIMEOUT];
+        area["name"="AREA_NAME"]->.searchArea;
+        (
+          QUERY(area.searchArea);
+        );
+        out body;
+        RECURSE
+        out skel qt;
+      TEMPLATE
+
+      # Creates a new request.
+      #
+      # @param query [String] the Overpass QL query body
+      # @param bbox [String, nil] the bounding box string from {BoundingBox}
+      # @param recurse [String, nil] the recurse operator (default: +">"+)
+      # @param area_name [String, nil] an OSM area name for area-based queries
+      def initialize(query, bbox = nil, recurse: '>', area_name: nil)
         @overpass_query = query
-        @global_bbox ||= "[#{bbox}]"
+        @global_bbox = bbox ? "[#{bbox}]" : ''
+        @recurse = recurse
+        @area_name = area_name
       end
 
-      # Performs the API request
-      def run
-        Net::HTTP.post_form(URI(API_URI), data: build_query)
+      # Converts the request into a complete Overpass QL query string.
+      #
+      # @return [String] the full query string ready for the API
+      def to_query
+        template = @area_name ? AREA_QUERY_TEMPLATE : QUERY_TEMPLATE
+        timeout = Underpass.configuration.timeout.to_s
+
+        result = template.sub('TIMEOUT', timeout)
+        result = result.sub('AREA_NAME', @area_name) if @area_name
+        result = result.sub('BBOX', @global_bbox) unless @area_name
+        result.sub('QUERY', @overpass_query)
+              .sub('RECURSE', recurse_statement)
       end
 
       private
 
-      def build_query
-        QUERY_TEMPLATE.sub('BBOX', @global_bbox)
-                      .sub('QUERY', @overpass_query)
+      def recurse_statement
+        return '' unless @recurse
+
+        "#{@recurse};\n"
       end
     end
   end

data/lib/underpass/ql/response.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Underpass
+  module QL
+    # Parses the JSON body of an Overpass API response into
+    # node, way, and relation lookup hashes keyed by element ID.
+    class Response
+      # Creates a new response by parsing the API response body.
+      #
+      # @param api_response [Net::HTTPResponse] the raw HTTP response
+      def initialize(api_response)
+        parsed_json = JSON.parse(api_response.body, symbolize_names: true)
+        @elements = parsed_json[:elements]
+      end
+
+      # Returns all node elements as a hash keyed by ID.
+      #
+      # @return [Hash{Integer => Hash}] node elements
+      def nodes
+        mapped_hash('node')
+      end
+
+      # Returns all way elements as a hash keyed by ID.
+      #
+      # @return [Hash{Integer => Hash}] way elements
+      def ways
+        mapped_hash('way')
+      end
+
+      # Returns all relation elements as a hash keyed by ID.
+      #
+      # @return [Hash{Integer => Hash}] relation elements
+      def relations
+        mapped_hash('relation')
+      end
+
+      private
+
+      def mapped_hash(type)
+        mapped_elements = elements_of_type(type).map do |element|
+          [element[:id], element]
+        end
+        mapped_elements.to_h
+      end
+
+      def elements_of_type(type)
+        @elements.select { |e| e[:type] == type }
+      end
+    end
+  end
+end

data/lib/underpass/shape.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module Underpass
+  # Converts OSM element data into RGeo geometry objects.
+  #
+  # All methods operate on the parsed response hashes produced by
+  # {QL::Response} and return RGeo geometries built with a WGS 84
+  # spherical factory.
+  class Shape
+    class << self
+      # Checks whether a way forms a closed ring (first node equals last node).
+      #
+      # @param way [Hash] a parsed way element
+      # @return [Boolean] +true+ if the way is closed
+      def open_way?(way)
+        way[:nodes].first == way[:nodes].last
+      end
+
+      # Builds an RGeo polygon from a closed way.
+      #
+      # @param way [Hash] a parsed way element
+      # @param nodes [Hash{Integer => Hash}] node lookup table
+      # @return [RGeo::Feature::Polygon] the polygon geometry
+      def polygon_from_way(way, nodes)
+        factory.polygon(line_string_from_way(way, nodes))
+      end
+
+      # Builds an RGeo line string from a way's node references.
+      #
+      # @param way [Hash] a parsed way element
+      # @param nodes [Hash{Integer => Hash}] node lookup table
+      # @return [RGeo::Feature::LineString] the line string geometry
+      def line_string_from_way(way, nodes)
+        factory.line_string(points_from_node_ids(way[:nodes], nodes))
+      end
+
+      # Builds an RGeo point from a node element.
+      #
+      # @param node [Hash] a parsed node element with +:lon+ and +:lat+ keys
+      # @return [RGeo::Feature::Point] the point geometry
+      def point_from_node(node)
+        factory.point(node[:lon], node[:lat])
+      end
+
+      # Assembles a multipolygon from a relation with outer and inner members.
+      #
+      # @param relation [Hash] a parsed relation element
+      # @param ways [Hash{Integer => Hash}] way lookup table
+      # @param nodes [Hash{Integer => Hash}] node lookup table
+      # @return [RGeo::Feature::Polygon, RGeo::Feature::MultiPolygon] a polygon
+      #   if only one outer ring, otherwise a multi-polygon
+      def multipolygon_from_relation(relation, ways, nodes)
+        outer_rings = build_rings(members_by_role(relation, 'outer'), ways, nodes)
+        inner_rings = build_rings(members_by_role(relation, 'inner'), ways, nodes)
+
+        polygons = outer_rings.map do |outer_ring|
+          factory.polygon(outer_ring, matching_inner_rings(outer_ring, inner_rings))
+        end
+
+        return polygons.first if polygons.size == 1
+
+        factory.multi_polygon(polygons)
+      end
+
+      # Assembles a multi-line-string from a route relation's way members.
+      #
+      # @param relation [Hash] a parsed relation element
+      # @param ways [Hash{Integer => Hash}] way lookup table
+      # @param nodes [Hash{Integer => Hash}] node lookup table
+      # @return [RGeo::Feature::MultiLineString] the multi-line-string geometry
+      def multi_line_string_from_relation(relation, ways, nodes)
+        way_members = relation[:members].select { |m| m[:type] == 'way' }
+        line_strings = way_members.filter_map do |member|
+          way = ways[member[:ref]]
+          next unless way
+
+          line_string_from_way(way, nodes)
+        end
+
+        factory.multi_line_string(line_strings)
+      end
+
+      # Returns the shared RGeo spherical factory (SRID 4326).
+      #
+      # @return [RGeo::Geographic::SphericalFactory] the factory instance
+      def factory
+        @factory ||= RGeo::Geographic.spherical_factory(srid: 4326)
+      end
+
+      private
+
+      def points_from_node_ids(node_ids, nodes)
+        node_ids.map { |n| factory.point(nodes[n][:lon], nodes[n][:lat]) }
+      end
+
+      def members_by_role(relation, role)
+        relation[:members]
+          .select { |m| m[:type] == 'way' && m[:role] == role }
+          .map { |m| m[:ref] }
+      end
+
+      def build_rings(way_ids, ways, nodes)
+        return [] if way_ids.empty?
+
+        sequences = WayChain.new(way_ids, ways).merged_sequences
+        sequences.map { |ids| factory.linear_ring(points_from_node_ids(ids, nodes)) }
+      end
+
+      def matching_inner_rings(outer_ring, inner_rings)
+        outer_polygon = factory.polygon(outer_ring)
+        inner_rings.select do |inner_ring|
+          point = inner_ring.points.first
+          outer_polygon.contains?(factory.point(point.x, point.y))
+        end
+      end
+    end
+  end
+end