Class: Underpass::QL::Query

Inherits:
Object
  • Object
show all
Defined in:
lib/underpass/ql/query.rb

Overview

High-level entry point for querying the Overpass API.

Glues together Request, Client, Response, QueryAnalyzer, and Matcher to provide a single-call interface.

Examples:

Query with a bounding box

features = Underpass::QL::Query.perform(bbox, 'way["building"="yes"];')

Query with a named area

features = Underpass::QL::Query.perform_in_area('Romania', 'node["place"="city"];')

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 Method Summary collapse

Class Method Details

.perform(bounding_box, query) ⇒ Array<Feature>

Queries the Overpass API within a bounding box.

Parameters:

  • bounding_box (RGeo::Feature::Geometry) —

    an RGeo polygon defining the search area

  • query (String, Builder) —

    an Overpass QL query string or a Builder instance

Returns:

  • (Array<Feature>) —

    the matched features

Raises:

  • (RateLimitError) —

    when rate limited after exhausting retries

  • (TimeoutError) —

    when the API times out after exhausting retries

  • (ApiError) —

    when the API returns an unexpected error



29
30
31
32
33
34
 
# File 'lib/underpass/ql/query.rb', line 29

def self.perform(bounding_box, query)
  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

.perform_in_area(area_name, query) ⇒ Array<Feature>

Queries the Overpass API within a named area (e.g. “Romania”).

Parameters:

  • area_name (String) —

    an OSM area name

  • query (String, Builder) —

    an Overpass QL query string or a Builder instance

Returns:

  • (Array<Feature>) —

    the matched features

Raises:

  • (RateLimitError) —

    when rate limited after exhausting retries

  • (TimeoutError) —

    when the API times out after exhausting retries

  • (ApiError) —

    when the API returns an unexpected error



44
45
46
47
48
 
# File 'lib/underpass/ql/query.rb', line 44

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

.perform_raw(query_body) ⇒ Array<Feature>

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.

Parameters:

  • query_body (String) —

    Overpass QL body with inline bbox (e.g. +‘node[“natural”=“peak”](47.0,25.0,47.1,25.1);’+)

Returns:

  • (Array<Feature>) —

    the matched features

Raises:

  • (RateLimitError) —

    when rate limited after exhausting retries

  • (TimeoutError) —

    when the API times out after exhausting retries

  • (ApiError) —

    when the API returns an unexpected error



60
61
62
63
 
# File 'lib/underpass/ql/query.rb', line 60

def self.perform_raw(query_body)
  request = Underpass::QL::Request.new(query_body, nil)
  execute(request, query_body)
end