RubyGems - underpass - Versions diffs - 0.0.7 → 0.9.1 - Mend

underpass 0.0.7 → 0.9.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (25) hide show

checksums.yaml +5 -5
data/README.md +497 -18
data/lib/underpass/cache.rb +45 -0
data/lib/underpass/client.rb +79 -0
data/lib/underpass/configuration.rb +28 -0
data/lib/underpass/error_parser.rb +140 -0
data/lib/underpass/errors.rb +76 -0
data/lib/underpass/feature.rb +34 -0
data/lib/underpass/filter.rb +56 -0
data/lib/underpass/geo_json.rb +23 -0
data/lib/underpass/matcher.rb +105 -0
data/lib/underpass/ql/bounding_box.rb +19 -6
data/lib/underpass/ql/builder.rb +97 -0
data/lib/underpass/ql/query.rb +72 -7
data/lib/underpass/ql/query_analyzer.rb +51 -0
data/lib/underpass/ql/request.rb +45 -12
data/lib/underpass/ql/response.rb +51 -0
data/lib/underpass/shape.rb +118 -0
data/lib/underpass/version.rb +2 -2
data/lib/underpass/way_chain.rb +71 -0
data/lib/underpass.rb +66 -19
metadata +26 -103
data/lib/underpass/ql/parser.rb +0 -72
data/lib/underpass/ql/ql.rb +0 -15
data/lib/underpass/ql/shape.rb +0 -40

data/lib/underpass/configuration.rb ADDED Viewed

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+module Underpass
+  # Stores configuration options for the Underpass library.
+  #
+  # @example
+  #   Underpass.configure do |config|
+  #     config.api_endpoint = 'https://overpass.kumi.systems/api/interpreter'
+  #     config.timeout = 30
+  #     config.max_retries = 5
+  #   end
+  class Configuration
+    # @return [String] the Overpass API endpoint URL
+    attr_accessor :api_endpoint
+    # @return [Integer] the query timeout in seconds
+    attr_accessor :timeout
+    # @return [Integer] maximum number of retry attempts for rate limiting and timeouts
+    attr_accessor :max_retries
+    def initialize
+      @api_endpoint = 'https://overpass-api.de/api/interpreter'
+      @timeout = 25
+      @max_retries = 3
+    end
+  end
+end

data/lib/underpass/error_parser.rb ADDED Viewed

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+module Underpass
+  # Parses HTML error responses from the Overpass API into structured data.
+  #
+  # The Overpass API returns HTML error pages when queries fail. This class
+  # extracts error information from those responses and returns structured
+  # hashes with code, message, and details.
+  #
+  # @example
+  #   result = ErrorParser.parse("<html>...runtime error: Query timed out...</html>", 504)
+  #   result[:code]    # => "timeout"
+  #   result[:message] # => "Query timed out in \"query\" at line 3 after 25 seconds."
+  #   result[:details] # => { line: 3, timeout_seconds: 25 }
+  class ErrorParser
+    # Known error patterns from Overpass API responses
+    PATTERNS = {
+      timeout: /Query timed out.*?at line (\d+) after (\d+) seconds/i,
+      memory: /Query run out of memory.*?(\d+)\s*MB/i,
+      syntax: /parse error:?\s*(.+)/i,
+      runtime: /runtime error:?\s*(.+)/i
+    }.freeze
+    # Parses an error response body and returns structured error data.
+    #
+    # @param response_body [String] the raw response body (usually HTML)
+    # @param status_code [Integer] the HTTP status code
+    # @return [Hash] structured error data with :code, :message, and :details keys
+    def self.parse(response_body, status_code)
+      return rate_limit_result if status_code == 429
+      text = extract_error_text(response_body)
+      parse_error_text(text, status_code)
+    end
+    # Extracts error text from HTML or returns the body as-is.
+    #
+    # @param body [String] the response body
+    # @return [String] the extracted error text
+    def self.extract_error_text(body)
+      return '' if body.nil? || body.empty?
+      # Try to extract text from <strong> tags (common Overpass error format)
+      if (match = body.match(%r{<strong[^>]*>(.*?)</strong>}im))
+        return match[1].gsub(/<[^>]+>/, '').strip
+      end
+      # Try to extract from <p> tags
+      if (match = body.match(%r{<p[^>]*>(.*?)</p>}im))
+        return match[1].gsub(/<[^>]+>/, '').strip
+      end
+      # Fall back to stripping all HTML tags
+      body.gsub(/<[^>]+>/, ' ').gsub(/\s+/, ' ').strip
+    end
+    private_class_method :extract_error_text
+    # Parses the error text against known patterns.
+    #
+    # @param text [String] the extracted error text
+    # @param status_code [Integer] the HTTP status code
+    # @return [Hash] structured error data
+    def self.parse_error_text(text, status_code)
+      parse_timeout(text) ||
+        parse_memory(text) ||
+        parse_syntax(text) ||
+        parse_runtime(text) ||
+        unknown_result(text, status_code)
+    end
+    private_class_method :parse_error_text
+    def self.parse_timeout(text)
+      return unless (match = text.match(PATTERNS[:timeout]))
+      { code: 'timeout', message: text, details: { line: match[1].to_i, timeout_seconds: match[2].to_i } }
+    end
+    private_class_method :parse_timeout
+    def self.parse_memory(text)
+      return unless (match = text.match(PATTERNS[:memory]))
+      { code: 'memory', message: text, details: { memory_mb: match[1].to_i } }
+    end
+    private_class_method :parse_memory
+    def self.parse_syntax(text)
+      return unless (match = text.match(PATTERNS[:syntax]))
+      { code: 'syntax', message: match[1].strip, details: extract_syntax_details(match[1]) }
+    end
+    private_class_method :parse_syntax
+    def self.parse_runtime(text)
+      return unless (match = text.match(PATTERNS[:runtime]))
+      { code: 'runtime', message: match[1].strip, details: {} }
+    end
+    private_class_method :parse_runtime
+    # Extracts line number from syntax error messages if present.
+    #
+    # @param message [String] the error message
+    # @return [Hash] details hash with line number if found
+    def self.extract_syntax_details(message)
+      if (match = message.match(/line\s+(\d+)/i))
+        { line: match[1].to_i }
+      else
+        {}
+      end
+    end
+    private_class_method :extract_syntax_details
+    # Returns a rate limit error result.
+    #
+    # @return [Hash] structured error data for rate limiting
+    def self.rate_limit_result
+      {
+        code: 'rate_limit',
+        message: 'Rate limited by the Overpass API',
+        details: {}
+      }
+    end
+    private_class_method :rate_limit_result
+    # Returns an unknown error result.
+    #
+    # @param text [String] the error text
+    # @param status_code [Integer] the HTTP status code
+    # @return [Hash] structured error data for unknown errors
+    def self.unknown_result(text, status_code)
+      message = text.empty? ? "HTTP #{status_code} error" : text
+      {
+        code: 'unknown',
+        message: message,
+        details: {}
+      }
+    end
+    private_class_method :unknown_result
+  end
+end

data/lib/underpass/errors.rb ADDED Viewed

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+require 'json'
+module Underpass
+  # Base error class for all Underpass errors.
+  #
+  # Provides structured error data parsed from Overpass API responses.
+  #
+  # @example
+  #   begin
+  #     features = Underpass::QL::Query.perform(bbox, query)
+  #   rescue Underpass::Error => e
+  #     e.code           # => "timeout"
+  #     e.error_message  # => "Query timed out..."
+  #     e.details        # => { line: 3, timeout_seconds: 25 }
+  #     e.http_status    # => 504
+  #     e.to_h           # => { code: "timeout", message: "...", details: {...} }
+  #   end
+  class Error < StandardError
+    # @return [String, nil] the error code (e.g., "timeout", "memory", "syntax")
+    attr_reader :code
+    # @return [String, nil] the human-readable error message
+    attr_reader :error_message
+    # @return [Hash] additional error details (varies by error type)
+    attr_reader :details
+    # @return [Integer, nil] the HTTP status code from the API response
+    attr_reader :http_status
+    # Creates a new error with optional structured data.
+    #
+    # @param message [String, nil] the error message (used by StandardError)
+    # @param code [String, nil] the error code
+    # @param error_message [String, nil] the detailed error message
+    # @param details [Hash] additional error details
+    # @param http_status [Integer, nil] the HTTP status code
+    def initialize(message = nil, code: nil, error_message: nil, details: {}, http_status: nil)
+      @code = code
+      @error_message = error_message || message
+      @details = details || {}
+      @http_status = http_status
+      super(@error_message || message)
+    end
+    # Returns a hash representation of the error.
+    #
+    # @return [Hash] the error as a hash with :code, :message, and :details keys
+    def to_h
+      {
+        code: code,
+        message: error_message,
+        details: details
+      }
+    end
+    # Returns a JSON representation of the error.
+    #
+    # @param args [Array] arguments passed to JSON.generate
+    # @return [String] the error as a JSON string
+    def to_json(*)
+      to_h.to_json(*)
+    end
+  end
+  # Raised when the Overpass API returns a 429 rate limit response.
+  class RateLimitError < Error; end
+  # Raised when the Overpass API returns a 504 timeout response.
+  class TimeoutError < Error; end
+  # Raised when the Overpass API returns an unexpected error response.
+  class ApiError < Error; end
+end

data/lib/underpass/feature.rb ADDED Viewed

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+module Underpass
+  # Wraps an RGeo geometry with OSM metadata (tags, id, type).
+  #
+  # Returned by {QL::Query.perform} and {Matcher#matches} for each matched
+  # element in the Overpass API response.
+  class Feature
+    # @return [RGeo::Feature::Geometry] the RGeo geometry object
+    attr_reader :geometry
+    # @return [Hash{Symbol => String}] the OSM tags for this element
+    attr_reader :properties
+    # @return [Integer, nil] the OSM element ID
+    attr_reader :id
+    # @return [String, nil] the OSM element type ("node", "way", or "relation")
+    attr_reader :type
+    # Creates a new Feature.
+    #
+    # @param geometry [RGeo::Feature::Geometry] the RGeo geometry
+    # @param properties [Hash] the OSM tags
+    # @param id [Integer, nil] the OSM element ID
+    # @param type [String, nil] the OSM element type
+    def initialize(geometry:, properties: {}, id: nil, type: nil)
+      @geometry = geometry
+      @properties = properties
+      @id = id
+      @type = type
+    end
+  end
+end

data/lib/underpass/filter.rb ADDED Viewed

@@ -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 ADDED Viewed

@@ -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 ADDED Viewed

@@ -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 CHANGED Viewed

@@ -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 ADDED Viewed

@@ -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 CHANGED Viewed

@@ -1,17 +1,82 @@
 # 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"];')
+    #
+    # @example Raw query with inline bounding box
+    #   query = 'node["name"="Peak"]["natural"="peak"](47.0,25.0,47.1,25.1);'
+    #   features = Underpass::QL::Query.perform_raw(query)
     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
+      # Executes a pre-built query body that includes its own inline bbox.
+      # Wraps it in the standard Request template for output format and timeout,
+      # without adding a global bounding box.
+      #
+      # @param query_body [String] Overpass QL body with inline bbox
+      #   (e.g. +'node["name"="Peak"]["natural"="peak"](47.0,25.0,47.1,25.1);'+)
+      # @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_raw(query_body)
+        request = Underpass::QL::Request.new(query_body, nil)
+        execute(request, query_body)
+      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