overture_maps 0.1.0

data/lib/overture_maps/bounding_box.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module OvertureMaps
+  # A WGS84 bounding box. The single place that parses user-supplied coordinate
+  # strings, so import and download entry points cannot drift apart.
+  class BoundingBox
+    NUMBER = /-?\d+(?:\.\d+)?/
+    # Four numbers separated by commas, whitespace, or underscores, with an
+    # optional "|display name" suffix: "47.6,-122.3,47.7,-122.2" or
+    # "47.6_-122.3_47.7_-122.2|seattle"
+    COORDS = /\A(#{NUMBER})[,\s_]+(#{NUMBER})[,\s_]+(#{NUMBER})[,\s_]+(#{NUMBER})(?:\|(.+))?\z/
+
+    attr_reader :min_lat, :min_lng, :max_lat, :max_lng, :display_name
+
+    def initialize(lat1:, lng1:, lat2:, lng2:, display_name: nil)
+      @min_lat, @max_lat = [Float(lat1), Float(lat2)].minmax
+      @min_lng, @max_lng = [Float(lng1), Float(lng2)].minmax
+      @display_name = display_name
+
+      unless (-90..90).cover?(@min_lat) && (-90..90).cover?(@max_lat) &&
+             (-180..180).cover?(@min_lng) && (-180..180).cover?(@max_lng)
+        raise ArgumentError, "coordinates out of range: #{self}"
+      end
+    end
+
+    # Returns a BoundingBox if the string looks like coordinates, else nil.
+    def self.parse(string)
+      match = COORDS.match(string.to_s.strip)
+      return nil unless match
+
+      new(lat1: match[1], lng1: match[2], lat2: match[3], lng2: match[4], display_name: match[5])
+    end
+
+    def self.coordinates?(string)
+      COORDS.match?(string.to_s.strip)
+    end
+
+    # Overture bbox structs come back from division searches as
+    # {"xmin" => ..., "xmax" => ..., "ymin" => ..., "ymax" => ...}
+    def self.from_overture(bbox, display_name: nil)
+      new(
+        lat1: bbox["ymin"], lng1: bbox["xmin"],
+        lat2: bbox["ymax"], lng2: bbox["xmax"],
+        display_name: display_name
+      )
+    end
+
+    def self.around(lat:, lng:, radius_meters:)
+      lat = Float(lat)
+      lng = Float(lng)
+      lat_delta = radius_meters.to_f / 111_000
+      lng_delta = radius_meters.to_f / (111_000 * Math.cos(lat * Math::PI / 180))
+
+      new(
+        lat1: [lat - lat_delta, -90].max, lng1: [lng - lng_delta, -180].max,
+        lat2: [lat + lat_delta, 90].min, lng2: [lng + lng_delta, 180].min
+      )
+    end
+
+    def to_s
+      "#{min_lat},#{min_lng},#{max_lat},#{max_lng}"
+    end
+
+    # Filename-safe label for cache files.
+    def slug
+      return sanitized_display_name if display_name
+
+      format("%.4f_%.4f_%.4f_%.4f", min_lat, min_lng, max_lat, max_lng)
+    end
+
+    private
+
+    # Filename-safe and idempotent: a slug that round-trips through
+    # display_name (e.g. from ImportedArea bookkeeping) must come back
+    # unchanged, so dots and dashes survive.
+    def sanitized_display_name
+      display_name.downcase.gsub(/[^a-z0-9.\-]+/, "_").gsub(/\A_+|_+\z/, "")
+    end
+  end
+end

data/lib/overture_maps/changelog.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module OvertureMaps
+  # Overture's per-release data changelog: parquet partitioned by theme,
+  # type, and change_type (added | removed | data_changed | unchanged),
+  # with each row carrying the feature id and its bbox. The changelog for
+  # release R describes changes relative to the release before R.
+  module Changelog
+    CHANGE_TYPES = %w[added removed data_changed unchanged].freeze
+
+    class << self
+      # IDs removed in `release` (relative to the prior release), optionally
+      # restricted to those whose bbox intersects the given area.
+      def removed_ids(theme:, type:, release:, bbox: nil)
+        sql, params = build_query(theme: theme, type: type, release: release,
+                                  change_type: "removed", bbox: bbox, select: "id")
+        QueryEngine.instance.query(sql, params).map { |row| row["id"] }
+      end
+
+      # Per-change_type counts for a release/theme/type (for sync:status and
+      # dry runs). Returns e.g. {"added" => 123, "removed" => 4, ...}.
+      def counts(theme:, type:, release:, bbox: nil)
+        validate!(theme, type)
+        source = source_glob(theme: theme, type: type, release: Releases.validate!(release),
+                             change_type: "*")
+        sql = +"SELECT change_type, count(*) AS n FROM read_parquet('#{source}', hive_partitioning=1)"
+        params = []
+        if bbox
+          sql << " WHERE bbox.xmin <= ? AND bbox.xmax >= ? AND bbox.ymin <= ? AND bbox.ymax >= ?"
+          params = bbox_params(bbox)
+        end
+        sql << " GROUP BY change_type"
+
+        QueryEngine.instance.query(sql, params)
+                   .to_h { |row| [row["change_type"], Integer(row["n"])] }
+      end
+
+      private
+
+      def build_query(theme:, type:, release:, change_type:, bbox:, select:)
+        validate!(theme, type)
+        raise ArgumentError, "unknown change_type: #{change_type}" unless CHANGE_TYPES.include?(change_type)
+
+        source = source_glob(theme: theme, type: type, release: Releases.validate!(release),
+                             change_type: change_type)
+        sql = +"SELECT #{select} FROM read_parquet('#{source}', hive_partitioning=1)"
+        params = []
+        if bbox
+          sql << " WHERE bbox.xmin <= ? AND bbox.xmax >= ? AND bbox.ymin <= ? AND bbox.ymax >= ?"
+          params = bbox_params(bbox)
+        end
+        [sql, params]
+      end
+
+      def bbox_params(bbox)
+        [bbox.max_lng, bbox.min_lng, bbox.max_lat, bbox.min_lat]
+      end
+
+      def source_glob(theme:, type:, release:, change_type:)
+        base = OvertureMaps.configuration.s3_uri.chomp("/")
+        "#{base}/changelog/#{release}/theme=#{theme}/type=#{type}/change_type=#{change_type}/*.parquet"
+      end
+
+      def validate!(theme, type)
+        types = Import::Downloader::TYPES[theme] or raise ArgumentError, "unknown theme: #{theme}"
+        raise ArgumentError, "unknown type #{type} for #{theme}" unless types.include?(type)
+      end
+    end
+  end
+end

data/lib/overture_maps/configuration.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module OvertureMaps
+  class Configuration
+    DEFAULT_S3_HTTP_URL = "https://overturemaps-us-west-2.s3.us-west-2.amazonaws.com"
+    DEFAULT_S3_URI = "s3://overturemaps-us-west-2"
+    DEFAULT_S3_REGION = "us-west-2"
+
+    # release: Overture release string (e.g. "2026-06-17.0"). nil means "latest available".
+    # cache_dir: where downloaded parquet extracts are stored.
+    # s3_http_url/s3_uri/s3_region: data source; point at a mirror (e.g. MinIO) to avoid
+    #   hitting Overture's bucket from every host.
+    # batch_size: default import batch size.
+    # timeout: HTTP open/read timeout in seconds.
+    # non_interactive: never prompt; pick the best division match and prefer fresh downloads.
+    # duckdb_cli_path: explicit path to the duckdb binary (otherwise PATH, then auto-download).
+    # logger: receives progress output; defaults to stdout logging from the rake layer.
+    # api_auth: callable invoked with the controller before every API
+    #   request; render/head inside it to reject (nil = open access).
+    # api_default_limit / api_max_limit: collection endpoint page sizing.
+    # tile_feature_limit: per-tile feature cap for the MVT endpoint.
+    attr_accessor :release, :cache_dir, :s3_http_url, :s3_uri, :s3_region,
+                  :batch_size, :timeout, :non_interactive, :duckdb_cli_path, :logger,
+                  :api_auth, :api_default_limit, :api_max_limit, :tile_feature_limit
+
+    def initialize
+      @release = nil
+      @cache_dir = "tmp/overture"
+      @s3_http_url = DEFAULT_S3_HTTP_URL
+      @s3_uri = DEFAULT_S3_URI
+      @s3_region = DEFAULT_S3_REGION
+      @batch_size = 1000
+      @timeout = 30
+      @non_interactive = !ENV["OVERTURE_NON_INTERACTIVE"].to_s.empty?
+      @duckdb_cli_path = ENV["OVERTURE_DUCKDB_CLI"]
+      @logger = nil
+      @api_auth = nil
+      @api_default_limit = 100
+      @api_max_limit = 1000
+      @tile_feature_limit = 20_000
+    end
+  end
+end

data/lib/overture_maps/database.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module OvertureMaps
+  # PostGIS helpers. Identifiers are quoted and values sanitized — nothing
+  # user-supplied is interpolated into SQL.
+  module Database
+    class << self
+      def postgis_available?
+        connection.extension_enabled?("postgis")
+      rescue StandardError
+        false
+      end
+
+      def enable_postgis
+        connection.execute("CREATE EXTENSION IF NOT EXISTS postgis")
+      end
+
+      def create_spatial_index(table_name, column_name = "geometry")
+        index = quote_ident("#{table_name}_#{column_name}_idx")
+        connection.execute(
+          "CREATE INDEX IF NOT EXISTS #{index} ON #{quote_ident(table_name)} " \
+          "USING GIST (#{quote_ident(column_name)})"
+        )
+      end
+
+      def drop_spatial_index(table_name, column_name = "geometry")
+        connection.execute("DROP INDEX IF EXISTS #{quote_ident("#{table_name}_#{column_name}_idx")}")
+      end
+
+      def reindex_spatial(table_name, column_name = "geometry")
+        connection.execute("REINDEX INDEX #{quote_ident("#{table_name}_#{column_name}_idx")}")
+      end
+
+      def geometry_info(table_name, column_name = "geometry")
+        exec_sanitized(
+          "SELECT type, srid FROM geometry_columns WHERE f_table_name = ? AND f_geometry_column = ?",
+          table_name.to_s, column_name.to_s
+        ).first
+      end
+
+      def bounding_box_query(table_name, south, west, north, east, column_name = "geometry")
+        exec_sanitized(
+          "SELECT * FROM #{quote_ident(table_name)} " \
+          "WHERE #{quote_ident(column_name)} && ST_MakeEnvelope(?, ?, ?, ?, 4326)::geography",
+          Float(west), Float(south), Float(east), Float(north)
+        )
+      end
+
+      def nearest_neighbors(table_name, lat, lng, limit = 10, column_name = "geometry")
+        column = quote_ident(column_name)
+        exec_sanitized(
+          "SELECT *, ST_Distance(#{column}, ST_SetSRID(ST_MakePoint(?, ?), 4326)::geography) AS distance " \
+          "FROM #{quote_ident(table_name)} " \
+          "ORDER BY #{column} <-> ST_SetSRID(ST_MakePoint(?, ?), 4326)::geography LIMIT ?",
+          Float(lng), Float(lat), Float(lng), Float(lat), Integer(limit)
+        )
+      end
+
+      private
+
+      def exec_sanitized(sql, *values)
+        connection.exec_query(ActiveRecord::Base.sanitize_sql([sql, *values]))
+      end
+
+      def connection
+        ActiveRecord::Base.connection
+      end
+
+      def quote_ident(name)
+        connection.quote_table_name(name.to_s)
+      end
+    end
+  end
+end

data/lib/overture_maps/division_search.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module OvertureMaps
+  # Resolves location names to division areas. Prefers the locally imported
+  # overture_divisions table (fast, offline); falls back to querying the
+  # divisions theme on Overture's bucket. Both paths return the same shape:
+  # { id:, name:, subtype:, country:, region:, bbox: BoundingBox, area_km2: }
+  # ordered largest-area first.
+  module DivisionSearch
+    class << self
+      def search(query:, release: nil, limit: 20)
+        local(query: query, limit: limit) ||
+          Import::Downloader.search_divisions(query: query, release: release, limit: limit)
+      end
+
+      # Returns nil (fall back to remote) when the table is missing, empty,
+      # unreachable, or has no match for the query.
+      def local(query:, limit: 20)
+        model = Models::Division
+        return nil unless model.table_exists?
+
+        rows = model.search_by_name(query).largest_first.limit(limit)
+        return nil if rows.empty?
+
+        rows.filter_map do |division|
+          bbox = division.to_bounding_box
+          next unless bbox
+
+          {
+            id: division.id,
+            name: division.name,
+            subtype: division.subtype,
+            country: division.country,
+            region: division.region,
+            bbox: bbox,
+            area_km2: Util.bbox_area_km2(bbox)
+          }
+        end.then { |results| results.empty? ? nil : results }
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end

data/lib/overture_maps/engine.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "rails/engine"
+
+module OvertureMaps
+  # Mountable engine providing the read-only query API over imported data:
+  #
+  #   # config/routes.rb (added by the install generator)
+  #   mount OvertureMaps::Engine => "/overture"
+  #
+  # Rake tasks under lib/tasks and the controllers under app/ are picked up
+  # by Rails::Engine's conventions — no manual loading here (a second load
+  # would define every rake task twice).
+  class Engine < ::Rails::Engine
+    isolate_namespace OvertureMaps
+
+    initializer "overture_maps.configure_rgeo" do
+      ActiveSupport.on_load(:active_record) do
+        require "rgeo/active_record"
+
+        RGeo::ActiveRecord::SpatialFactoryStore.instance.tap do |store|
+          factory = RGeo::Geographic.spherical_factory(srid: 4326)
+          store.default = factory
+          %w[geometry geometry_collection line_string multi_line_string
+             multi_point multi_polygon point polygon].each do |geo_type|
+            store.register(factory, geo_type: geo_type)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/overture_maps/geometry_parser.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "rgeo"
+require "rgeo/geo_json"
+
+module OvertureMaps
+  # Parses the geometry encodings Overture data shows up in: WKB (binary or
+  # hex, from parquet), WKT (from DuckDB text output), and GeoJSON (hash or
+  # string). Returns RGeo features on the spherical WGS84 factory.
+  module GeometryParser
+    module_function
+
+    def factory
+      @factory ||= RGeo::Geographic.spherical_factory(srid: 4326)
+    end
+
+    def parse(geom)
+      return nil if geom.nil?
+      return geom if geom.is_a?(RGeo::Feature::Instance)
+
+      case geom
+      when Hash
+        RGeo::GeoJSON.decode(geom, geo_factory: factory)
+      when String
+        parse_string(geom)
+      end
+    end
+
+    def parse_string(geom)
+      stripped = geom.strip
+      if stripped.start_with?("{")
+        RGeo::GeoJSON.decode(stripped, geo_factory: factory)
+      elsif stripped.match?(/\A[A-Za-z]/)
+        factory.parse_wkt(stripped)
+      else
+        # Binary or hex WKB; RGeo's parser auto-detects hex strings.
+        factory.parse_wkb(geom)
+      end
+    end
+  end
+end

data/lib/overture_maps/gers.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module OvertureMaps
+  # GERS — Overture's Global Entity Reference System. IDs are dashed UUIDs
+  # (since June 2025); earlier releases used 32-char undashed hex.
+  module GERS
+    UUID_FORMAT = /\A\h{8}-\h{4}-\h{4}-\h{4}-\h{12}\z/
+    LEGACY_FORMAT = /\A\h{32}\z/
+
+    class << self
+      def valid_id?(id)
+        id.is_a?(String) && (id.match?(UUID_FORMAT) || id.match?(LEGACY_FORMAT))
+      end
+
+      # Looks an id up in the official registry (the unversioned source of
+      # truth for all published GERS ids). Returns a hash with keys like
+      # "version", "first_seen", "last_seen", "last_changed", "path", "bbox",
+      # or nil when unknown. Scans registry parquet on S3 — takes seconds.
+      def lookup(id)
+        raise ArgumentError, "not a GERS id: #{id.inspect}" unless valid_id?(id)
+
+        source = "#{OvertureMaps.configuration.s3_uri.chomp("/")}/registry/*.parquet"
+        rows = QueryEngine.instance.query(
+          "SELECT * FROM read_parquet('#{source}') WHERE id = ? LIMIT 1", [id]
+        )
+        rows.first
+      end
+    end
+  end
+end

data/lib/overture_maps/import/downloader.rb

@@ -0,0 +1,248 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module OvertureMaps
+  module Import
+    # Downloads Overture data: whole theme files via anonymous HTTP, and
+    # bbox-filtered extracts via DuckDB (which pushes the bbox predicate down
+    # to parquet row-group statistics, so only the relevant slice of the
+    # dataset is transferred).
+    class Downloader
+      THEMES = %w[addresses base buildings divisions places transportation].freeze
+
+      TYPES = {
+        "addresses" => %w[address],
+        "base" => %w[bathymetry infrastructure land land_cover land_use water],
+        "buildings" => %w[building building_part],
+        "divisions" => %w[division division_area division_boundary],
+        "places" => %w[place],
+        "transportation" => %w[connector segment]
+      }.freeze
+
+      # division_area subtypes worth surfacing in a name search, roughly
+      # largest to smallest.
+      DIVISION_SUBTYPES = %w[country dependency region county localadmin locality borough neighborhood].freeze
+
+      # Division areas smaller than this are sliver noise in a name search
+      # (ported from the parallel main-branch work, commit 6305670).
+      MIN_SEARCH_AREA_KM2 = 1.0
+
+      EXTRACT_FORMATS = {
+        "parquet" => "parquet",
+        "geojson" => "geojson",
+        "geojsonseq" => "geojsonseq",
+        "gpkg" => "gpkg",
+        "geopackage" => "gpkg"
+      }.freeze
+
+      attr_reader :theme, :type, :release, :output_dir
+
+      def initialize(theme:, type: nil, release: nil, output_dir: nil)
+        raise ArgumentError, "unknown theme: #{theme}" unless THEMES.include?(theme)
+        raise ArgumentError, "unknown type #{type} for #{theme}" if type && !TYPES[theme].include?(type)
+
+        @theme = theme
+        @type = type
+        @release = Releases.validate!(release || Releases.current)
+        @output_dir = output_dir || OvertureMaps.configuration.cache_dir
+      end
+
+      def self.types_for_theme(theme)
+        TYPES[theme] || []
+      end
+
+      def self.themes_with_types
+        TYPES
+      end
+
+      # Downloads the complete parquet files for this theme/type. These are
+      # large (buildings alone is hundreds of GB globally) — bbox extracts
+      # are almost always what you want instead.
+      def download_theme_files
+        files = list_files
+        if files.empty?
+          log "No files found for #{theme}#{type ? "/#{type}" : ""} in #{release}"
+          return 0
+        end
+
+        log "Found #{files.count} file(s) to download..."
+        FileUtils.mkdir_p(output_dir)
+
+        files.each do |file|
+          filename = File.basename(file[:key])
+          local_path = File.join(output_dir, filename)
+
+          result = Storage.download(file[:key], to: local_path, expected_size: file[:size])
+          if result == :skipped
+            log "Skipping #{filename} (already exists)"
+          else
+            log "Downloaded #{filename} (#{Util.format_size(file[:size])})"
+          end
+        end
+
+        files.count
+      end
+
+      # Writes a bbox-filtered extract for one type to a local file and
+      # returns its path (nil when the area has no data). The extract is
+      # named by theme/type/release/area, so later runs reuse it as a cache.
+      def extract_bbox(bbox, format: "parquet", output_path: nil, limit: nil)
+        target_type = type or raise ArgumentError, "extract_bbox requires a type"
+        path = output_path || extract_path(bbox, format: format)
+        FileUtils.mkdir_p(File.dirname(path))
+
+        sql, params = self.class.bbox_query(theme: theme, type: target_type, release: release,
+                                            bbox: bbox, limit: limit)
+        begin
+          QueryEngine.instance.copy_to(sql, params: params, output_path: path,
+                                       format: EXTRACT_FORMATS.fetch(format.to_s.downcase, "parquet"))
+        rescue QueryEngine::Error, StandardError => e
+          raise release_hint_error(e)
+        end
+
+        if File.exist?(path) && File.size(path).positive?
+          path
+        else
+          FileUtils.rm_f(path)
+          nil
+        end
+      end
+
+      # Extracts every type in the theme for a bbox. Returns the paths written.
+      def extract_bbox_all_types(bbox, format: "parquet")
+        types = type ? [type] : TYPES.fetch(theme)
+        types.filter_map do |t|
+          log "Querying #{theme}/#{t} (#{release})..."
+          path = self.class.new(theme: theme, type: t, release: release, output_dir: output_dir)
+                     .extract_bbox(bbox, format: format)
+          log(path ? "  Saved #{File.basename(path)} (#{Util.format_size(File.size(path))})" : "  No data found")
+          path
+        end
+      end
+
+      def extract_nearby(lat:, lng:, radius_meters:, format: "parquet")
+        extract_bbox_all_types(BoundingBox.around(lat: lat, lng: lng, radius_meters: radius_meters), format: format)
+      end
+
+      # The cache path for a bbox extract of this theme/type/release.
+      def extract_path(bbox, format: "parquet")
+        ext = EXTRACT_FORMATS.fetch(format.to_s.downcase, "parquet")
+        File.join(output_dir, "#{theme}_#{type}_#{release}_#{bbox.slug}.#{ext}")
+      end
+
+      # An existing extract for this theme/type/release/area, or nil. Matches
+      # exactly — never falls back to "some other file for the theme".
+      def cached_extract(bbox, format: "parquet")
+        path = extract_path(bbox, format: format)
+        File.exist?(path) && File.size(path).positive? ? path : nil
+      end
+
+      def list_files
+        prefix = "release/#{release}/theme=#{theme}#{type ? "/type=#{type}" : ""}"
+        Storage.list(prefix: prefix)[:objects].select { |o| o[:key].end_with?(".parquet") }
+      end
+
+      def self.list_types(theme:, release: nil)
+        release = Releases.validate!(release || Releases.current)
+        listing = Storage.list(prefix: "release/#{release}/theme=#{theme}/", delimiter: "/")
+        listing[:prefixes].filter_map { |p| p[/type=([^\/]+)/, 1] }.sort
+      end
+
+      def self.list_themes(release: nil)
+        release = Releases.validate!(release || Releases.current)
+        listing = Storage.list(prefix: "release/#{release}/", delimiter: "/")
+        listing[:prefixes].filter_map { |p| p[/theme=([^\/]+)/, 1] }.sort
+      end
+
+      # Searches division areas by name. Returns hashes with :id, :name,
+      # :subtype, :country, :region, :bbox (BoundingBox) and :area_km2,
+      # largest areas first.
+      def self.search_divisions(query:, release: nil, limit: 20)
+        release = Releases.validate!(release || Releases.current)
+        source = source_glob(theme: "divisions", type: "division_area", release: release)
+        placeholders = DIVISION_SUBTYPES.map { "?" }.join(", ")
+
+        sql = <<~SQL
+          SELECT id, names.primary AS name, subtype, country, region,
+                 bbox.xmin AS xmin, bbox.xmax AS xmax, bbox.ymin AS ymin, bbox.ymax AS ymax
+          FROM read_parquet('#{source}', hive_partitioning=1)
+          WHERE names.primary ILIKE ?
+            AND subtype IN (#{placeholders})
+            AND bbox.xmax > bbox.xmin AND bbox.ymax > bbox.ymin
+          ORDER BY (bbox.xmax - bbox.xmin) * (bbox.ymax - bbox.ymin) DESC
+          LIMIT #{Integer(limit)}
+        SQL
+
+        rows = QueryEngine.instance.query(sql, ["%#{query}%"] + DIVISION_SUBTYPES)
+        results = rows.map do |row|
+          bbox = BoundingBox.new(
+            lat1: row["ymin"], lng1: row["xmin"],
+            lat2: row["ymax"], lng2: row["xmax"],
+            display_name: row["name"]
+          )
+          {
+            id: row["id"],
+            name: row["name"],
+            subtype: row["subtype"],
+            country: row["country"],
+            region: row["region"],
+            bbox: bbox,
+            area_km2: Util.bbox_area_km2(bbox)
+          }
+        end
+        results.select { |r| r[:area_km2] >= MIN_SEARCH_AREA_KM2 }
+      end
+
+      # Builds the bbox-filtered SELECT for one theme/type. Intersection
+      # semantics: any feature whose bbox overlaps the query box is included,
+      # matching what "give me this area" means (the old strict-containment
+      # filter silently dropped everything touching the boundary).
+      def self.bbox_query(theme:, type:, release:, bbox:, limit: nil)
+        raise ArgumentError, "unknown theme: #{theme}" unless THEMES.include?(theme)
+        raise ArgumentError, "unknown type #{type} for #{theme}" unless TYPES[theme].include?(type)
+
+        source = source_glob(theme: theme, type: type, release: Releases.validate!(release))
+        sql = <<~SQL
+          SELECT *
+          FROM read_parquet('#{source}', hive_partitioning=1)
+          WHERE bbox.xmin <= ? AND bbox.xmax >= ?
+            AND bbox.ymin <= ? AND bbox.ymax >= ?
+        SQL
+        sql += "LIMIT #{Integer(limit)}\n" if limit
+        [sql, [bbox.max_lng, bbox.min_lng, bbox.max_lat, bbox.min_lat]]
+      end
+
+      def self.source_glob(theme:, type:, release:)
+        "#{OvertureMaps.configuration.s3_uri.chomp("/")}/release/#{release}/theme=#{theme}/type=#{type}/*.parquet"
+      end
+
+      private
+
+      # Overture prunes old releases; a query against a missing one fails
+      # with an opaque DuckDB error. Add the available releases when the
+      # requested one isn't in the catalog.
+      def release_hint_error(error)
+        available = begin
+          Releases.all
+        rescue StandardError
+          nil
+        end
+
+        if available && !available.include?(release)
+          Import::Error.new(
+            "release #{release} is not available (available: #{available.join(", ")}); " \
+            "original error: #{error.message}"
+          )
+        else
+          error
+        end
+      end
+
+      def log(message)
+        logger = OvertureMaps.configuration.logger
+        logger ? logger.info(message) : puts(message)
+      end
+    end
+  end
+end